Skip to content

Supplement a @mixin #2954

Open
Open

Description

@bilogic

Related to

I have 2 problems that I think @mixin can help, but unsure how

  1. Some packages have 0 comments, e.g. https://github.com/filamentphp/filament, makes it hard to write their code without constantly having look up the documentation. I would like to be able to inject comments for the various 3rd party methods

  2. Be able to jump to 3rd party methods even though they choose not to include @mixin ...

Is there a way I can inject such info into phpactor?

Activity

  1. dantleech commented on Nov 26, 2025

    @dantleech
    Collaborator

    I would like to be able to inject comments for the various 3rd party methods

    I assume you mean through the use of stubs?

  2. bilogic commented on Nov 26, 2025

    @bilogic
    Author

    I'm not sure how stubs work, any URL/references?

  3. bilogic commented on Nov 26, 2025

    @bilogic
    Author
  4. dantleech commented on Nov 29, 2025

    @dantleech
    Collaborator

    It can now as "Additive stubs" (just merged #2968 ): https://phpactor.readthedocs.io/en/master/reference/stubs.html

    If you're on the master branch you can configure "worse_reflection.additive_stubs": [ "path/to/wordpresssetubs.php"] or similar.

  5. bilogic commented on Nov 29, 2025

    @bilogic
    Author
    Image

    Thanks, don't mean to be a pain but it doesn't seem to be working, I would like to read the docblock, but instead it only says method brandName when my mouse hovers over the code.

  6. dantleech commented on Nov 29, 2025

    @dantleech
    Collaborator

    Can you share the applicable phpactor config? I tested this with:

    # .phpactor.json
    {
        "worse_reflection.additive_stubs": [
            "_ide_helper.php",
            "_ide_helper_models.php"
        ],
        "indexer.include_patterns": [
            "/app/**/*.php",
            "/tests/**/*.php"
        ],
        // other config
    }
    
  7. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    {
        "$schema": "/home/user/.local/share/code-server/extensions/phpactor.vscode-phpactor-1.7.5-universal/vendor/phpactor/phpactor/phpactor.schema.json",
        "worse_reflection.additive_stubs": [
            "./ours/my/package/stubs/*.php",
            "./ours/my/package/stubs/Filament/Panel.php"
        ],
        "language_server_phpstan.enabled": false
    }
    
  8. dantleech commented on Nov 30, 2025

    @dantleech
    Collaborator

    Wild cards are not supported, with the current implementation you need to include each stub file individually - and indeed you should have received a notification in your IDE that *.php was invalid?

    As noted in the docs you should also include only the source files for your project (as in my example above). What are ours/my/package/stubs? Are these in vendor? are those folders contained in your project source tree (i.e. src/, app/, vendor/ etc?)

  9. bilogic commented on Nov 30, 2025

    @bilogic
    Author

    To be clear,

    1. 3rd party located here ./vendor/filament/filament/src/Panel.php
    2. My additive here ./ours/my/package/stubs/Filament/Panel.php, i.e. it contains a subset of 1, not everything
    3. And my sources are in ./app/**/*.php, ./tests/**/*.php, ./ours/**/*.php and ./vendor/**/*.php
    4. I think there was a problem in 2 earlier, I'm seeing my additive comments now after fixing
      Image
    5. But a new problem: 1 has databaseNotifications and 2 does not, VSCode is complaining it cannot find databaseNotifications, well, it's definitely in 1
      Image
    6. My setup is a bit different from _ide_helper.php, they need to constantly re-generate the stub. Mine is part of a composer package, the thinking is, once I include this package, my Filament methods magically gets extra documentation, are you saying that folders of addictive_stubs and indexer.include_patterns cannot overlap?
  10. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    {
        "$schema": "/home/user/.local/share/code-server/extensions/phpactor.vscode-phpactor-1.7.5-universal/vendor/phpactor/phpactor/phpactor.schema.json",
        "worse_reflection.additive_stubs": [
            "./stubs/Filament/Panel.php"
        ],
        "indexer.include_patterns": [
            "/app/**/*.php",
            "/ours/**/*.php",
            "/tests/**/*.php",
            "/vendor/**/*.php"
        ],
        "language_server_phpstan.enabled": false
    }

    I tested not overlapping, now I lost my additive comments

  11. dantleech commented on Nov 30, 2025

    @dantleech
    Collaborator

    But a new problem: 1 has databaseNotifications and 2 does not, VSCode is complaining it cannot find databaseNotifications, well, it's definitely in 1

    I'd need to see your additive Panel stub - is it somehow autogenerated by Laravel or is it something you're generating yourself?

    are you saying that folders of addictive_stubs and indexer.include_patterns cannot overlap?

    they can overlap but the stub files should not be indexed - for example it's fine if you name the file Panel.stub (as long as you're indexing **/*.php files). This aligns closely with Phpstan's stub file feature. The main issue is that Phpactor would be unable to determine which of the class definitions are the "real" one.

  12. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    • Actual PHP class https://github.com/filamentphp/filament/blob/4.x/packages/panels/src/Panel.php
    • my stub
      <?php
      
      // my stub
      // located at ./ours/my/package/stubs/Filament/Panel.php
      
      namespace Filament;
      
      class Panel
      {
          /**
           * If true, this panel will be returned when `app('filament')` is called
           */
          public function default(string $condition = ''): static
          {
              return $this;
          }
      
          /**
           * Text to show at top-left corner of filament UI
           */
          public function brandName(string $condition = ''): static
          {
              return $this;
          }
      }
  13. dantleech commented on Nov 30, 2025

    @dantleech
    Collaborator

    This seems to work fine for me:

    Image Image
        "worse_reflection.additive_stubs": [
            "stubs/panel.stub",
            "_ide_helper.php",
            "_ide_helper_models.php"
        ],
        "indexer.include_patterns": [
            "/app/**/*.php",
            "/tests/**/*.php"
        ],
    
  14. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    1. I tried renaming to stub and all, still not working for me, I'm not using a big project and it has to index 55050 files
    2. Does /vendor/**/*.php have to be in indexer.include_patterns? I see you don't have it, that means you are likely not indexing the actual PHP class, what happens when you press F12 or hover over ->databaseNotifications()?
    3. And I noticed you don't use relative paths like ./app/..., I suppose it doesn't matter but that limits the paths to children only
    4. Any way to get some logs about what phpactor did with additive_stubs?

    My current situation

    1. I can get my own comments, but ->databaseNotifications() don't work, i.e. Method "databaseNotifications" does not exists on class
    2. OR I can get ->databaseNotifications() to be found, but own comments don't show up
  15. dantleech commented on Nov 30, 2025

    @dantleech
    Collaborator

    Does /vendor/**/*.php have to be in indexer.include_patterns?

    Ignore that, it was in there but deleted it along with several other paths for that example.

    And I noticed you don't use relative paths

    Absolute and relative paths should work.

    Any way to get some logs about what phpactor did with

    No - but if you change the path to a non-existing file, then you should get a notification in the IDE about that. therwise the stubs were loaded as expected.


    If you use my example above exactly (i.e. create new Panel) does it work?

  16. bilogic commented on Nov 30, 2025

    @bilogic
    Author

    Absolute and relative paths should work.

    Is "/app/**/*.php" a relative path? If yes, then how does an absolute path look? Otherwise I get it.

    If you use my example above exactly (i.e. create new Panel) does it work?

    This should make it easier https://github.com/bilogic/phpactor-additive-stubs and below is what I'm seeing: not showing my custom comments, let me know what you are seeing thanks

    1. Image
    2. Image
  17. dantleech commented on Nov 30, 2025

    @dantleech
    Collaborator

    Is "/app/**/*.php" a relative path?

    the include and exclude paths are confusing, they are, by design, "absolute" to the project root - but you can also just have app/**/*.php. I think we're probably confusing eachother.

    Strangely it seems to work for me without modification:

    Image Image

    Are you on the latest master version of phpactor?

  18. bilogic commented on Nov 30, 2025

    @bilogic
    Author

    Mine is pulled in by vscode-phpactor on openvsx, dated 3rd Nov 2025, how do I tell the version of phpactor?

    Image
  19. bilogic commented on Nov 30, 2025

    @bilogic
    Author

    Absolute paths are referenced to the filesystem, while relative paths will usually start from where the .phpactor.json is, using any other definition will be confusing :)

    So if /app/Test.php is relative to .phpactor.json, it is impossible to specify an absolute path

    Instead, if I wrote ./app/Test.php, this is clearly a path relative to .phpactor.json
    And to give an absolute path, that would be /usr/bin/local/composer

  20. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    Image

    I'm seeing 2025.10.17 which matches the latest release of phpactor

  21. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    1. Looking at your screenshots, are you using VSCode, aka vscode-phpactor? Or something else?
    2. Is there a way to dump out what phpactor indexed? It's probably the easiest way to figure out what's the issue
    3. I'm out of ideas
  22. bilogic commented on Nov 30, 2025

    @bilogic
    Author
    Image

    Phpactor\MapResolver\InvalidMap: Key(s) "worse_reflection.additive_stubs" are not known, known keys:...

    worse_reflection.additive_stubs is not a known key?

  23. dantleech commented on Nov 30, 2025

    @dantleech
    Collaborator

    Absolute paths are referenced to the filesystem

    absolute paths are referenced to the tree against which they are applied. The tree in this case is a workspace that is your project. but it doesn't matter 🙁

    looking at your screenshots, are you using VSCode

    I'm using Neovim

    I'm seeing 2025.10.17 which matches the latest release of phpactor

    and this is the problem. In the original comment I said If you're on the master branch you can configure "worse_reflection.additive_stubs". You're not on that branch as there hasn't been a release since I committed this feature yesterday. If you want to use this feature before the next release you'll need to clone phactor from github and configure VS code to use it.

    I should probably also make Phactor emmit warnings in the IDE when undefined keys are specified in the configuration


    in anycase I appreciate your efforts here, it's helps me understand how others are/will use this feature.

  24. bilogic commented on Dec 1, 2025

    @bilogic
    Author

    I tried to manually update my VSCode's vendor folder, but was still getting the same results. Please let me know when it reaches production. Thank you.

  25. FatBoyXPC commented on Dec 1, 2025

    @FatBoyXPC

    Thank you so much for this! I'll get working on adding this to my config!

  26. bilogic commented on Dec 12, 2025

    @bilogic
    Author

    @dantleech can make a release?

  27. dantleech commented on Dec 12, 2025

    @dantleech
    Collaborator

    it won't happen for a few weeks and then it will probably take another few weeks for the VS code package to be updated. I would consider cloning phactor and somehow configuring VS code to use the bleeding edge version. This would also help validate the feature and ensure that it solves your issue.

  28. bilogic commented on Dec 22, 2025

    @bilogic
    Author

    Sure, but I think it is more flexible if phpactor version can be selected from within the VSCode extension

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions