Extension Method Stub Generator Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the package as a Composer plugin in your project's composer.json:

   {
       "require": {
           "berry/extension-method-stub-generator": "^1.0"
       },
       "extra": {
           "berry": {
               "extension-method-stub-generator": {
                   "output_dir": "stubs"
               }
           }
       }
   }
   

   Run composer require berry/extension-method-stub-generator --dev.

2. First Use Case:

   • Ensure a dependency (e.g., berry/htmx) includes a berry-method-extensions.json file.
   • Run composer berry:generate-stubs to generate stubs in the configured output_dir (default: stubs).
   • Place stubs in your IDE’s metadata directory (e.g., vendor/ide-helper/) or configure your IDE to use the stubs folder.

Implementation Patterns

Workflow Integration

1. Dependency Scanning:

   • The plugin scans all dependencies for berry-method-extensions.json. Manually trigger generation via:

     composer berry:generate-stubs
     

   • Automate with a post-install-cmd or post-update-cmd in composer.json:

     "scripts": {
         "post-install-cmd": [
             "@berry:generate-stubs"
         ],
         "post-update-cmd": [
             "@berry:generate-stubs"
         ]
     }
     

2. Stub Usage:

   • IDE Support: Configure PHPStorm/VSCode to use the generated stubs:
     • PHPStorm: Add stubs/ to "Language Level and Dialect" → "Stub files".
     • VSCode: Use the php-ide extension and point to the stubs directory.
   • Static Analysis: Place stubs in vendor/ide-helper/ for tools like PHPStan to recognize extension methods.

3. Customization:

   • Override the default output_dir in composer.json:

     "extra": {
         "berry": {
             "extension-method-stub-generator": {
                 "output_dir": "custom-stubs"
             }
         }
     }
     

   • Extend stub generation by creating a custom berry-method-extensions.json in your project (merged with dependencies).

Gotchas and Tips

Pitfalls

1. Missing Config File:

   • If a dependency lacks berry-method-extensions.json, the plugin silently skips it. Verify dependencies manually:

     composer show --installed | grep berry
     

   • Fix: Contact package maintainers to add the config file.

2. Stub Overwriting:

   • Regenerating stubs overwrites existing files. Backup or version-control the stubs/ directory.

3. IDE Cache Issues:

   • After generating stubs, restart your IDE or manually refresh metadata:
     • PHPStorm: File → Invalidate Caches.
     • VSCode: Reload the window (Ctrl+Shift+P → "Reload Window").

Debugging

• Verbose Output: Run with -v to debug:

  composer berry:generate-stubs -v
  

• Manual Generation: Test stub generation for a single package:

  composer berry:generate-stubs --package=berry/htmx
  

Extension Points

1. Custom Templates:

   • Fork the plugin to modify stub templates (e.g., add PHPDoc tags). Override the StubGenerator class in a custom plugin.

2. Post-Processing:

   • Use a post-autoload-dump script to regenerate stubs after Composer updates:

     "scripts": {
         "post-autoload-dump": [
             "@berry:generate-stubs"
         ]
     }
     

3. CI/CD Integration:

   • Add stub generation to your CI pipeline (e.g., GitHub Actions) to ensure consistency:

     - run: composer berry:generate-stubs
     

Pro Tips

• Combine with phpstan/extension-installer: Use both packages to auto-load stubs for PHPStan:

  composer require --dev phpstan/extension-installer
  

  Configure phpstan.neon:

  includes:
      - vendor/berry-extension-method-stub-generator/stubs