Extension Method Stub Generator Laravel Package

Technical Evaluation

Architecture Fit

• Low Coupling: The package is a Composer plugin, meaning it operates at the dependency management layer rather than modifying core Laravel/PHP runtime behavior. This minimizes direct architectural impact on existing Laravel applications.
• IDE/Static Analysis Focus: Primarily targets PHPStan and IDE stub generation (e.g., PHPStorm), not runtime logic. Aligns well with Laravel’s reliance on static analysis for maintainability (e.g., phpstan/extension-installer).
• Berry Framework Dependency: Tightly coupled to the Berry PHP framework (e.g., berry/htmx). If the Laravel project doesn’t use Berry, the package is irrelevant unless extended for Laravel-specific stubs.
• Laravel Compatibility: No Laravel-specific hooks or service providers are required, but the generated stubs must conform to Laravel’s autoloading (PSR-4) and namespace conventions.

Integration Feasibility

• Zero Runtime Overhead: Since stubs are generated during composer install/update, no runtime performance impact exists.
• Static Analysis Integration:
  • Works seamlessly with PHPStan (via phpstan/extension-installer).
  • IDE stubs (e.g., PHPStorm) will auto-detect generated files if placed in stubs/ or vendor/ (configurable).
• Customization Potential:
  • Can be adapted to generate stubs for Laravel-specific classes (e.g., Illuminate\Support\Collection extensions) by defining custom berry-method-extensions.json.
  • Example: Extend Collection with berry/laravel-collection-extensions.json for domain-specific methods.

Technical Risk

• Berry Framework Lock-in: The package assumes Berry’s extension format. High risk if the project lacks Berry dependencies or needs non-Berry stubs.
• Stub File Conflicts: Generated stubs may clash with existing files (e.g., vendor/autoload.php overrides). Mitigate by:
  • Placing stubs in stubs/ (excluded from vendor/).
  • Using autoload-dev in composer.json for IDE-only files.
• IDE-Specific Behavior: Stub generation relies on IDE support for *.stub.php files. PHPStorm works out-of-the-box; other IDEs (e.g., VSCode) may require manual configuration.
• Maintenance Burden: If the package evolves (e.g., adds Laravel support), the project may need to fork or patch it.

Key Questions

1. Does the project use Berry PHP or need Berry-compatible stubs?
   • If not, is there a use case for generating stubs for Laravel’s own classes (e.g., Illuminate\* extensions)?
2. How will stubs be organized?
   • Should they live in stubs/ (recommended) or vendor/ (riskier)?
   • Will they be committed to version control or generated dynamically?
3. What static analysis tools are in use?
   • PHPStan (native support), Psalm, or custom tools? Ensure compatibility.
4. Are there existing stub generation tools?
   • Compare with phpstan/extension-installer or rubix/mls for overlap.
5. How will CI/CD handle stub generation?
   • Should composer install trigger stub generation, or is a separate step needed?

Integration Approach

Stack Fit

• Composer Plugin: Fits Laravel’s dependency management stack natively. No additional tooling required beyond Composer.
• Static Analysis Tools:
  • PHPStan: Directly compatible via extension-classes config or phpstan/extension-installer.
  • Psalm: May need manual configuration for stub paths.
  • IDE Support: PHPStorm/VSCode will auto-detect stubs if placed in standard locations.
• Laravel-Specific Adaptations:
  • Option 1: Use as-is for Berry dependencies (low effort).
  • Option 2: Extend to generate Laravel stubs by:
    • Creating a custom berry-method-extensions.json for Laravel classes.
    • Example:

      {
        "extensions": [
          {
            "namespace": "App\\Extensions",
            "class": ["Illuminate\\Support\\Collection"],
            "methods": [
              {
                "name": "toJsonApi",
                "doc": "Converts collection to JSON:API format",
                "returns": "array"
              }
            ]
          }
        ]
      }
      

  • Option 3: Fork the package to add Laravel-specific templates.

Migration Path

1. Assessment Phase:
   • Audit dependencies for Berry usage. If none, evaluate Laravel-specific stub needs.
   • Test stub generation in a staging environment with a sample berry-method-extensions.json.
2. Pilot Integration:
   • Add the package to composer.json under require-dev:

     "require-dev": {
       "berry/extension-method-stub-generator": "^1.0"
     }
     

   • Create a minimal berry-method-extensions.json (e.g., for a Berry dependency or custom Laravel class).
   • Run composer install to generate stubs.
3. Validation:
   • Verify stubs appear in stubs/ or vendor/ (adjust paths in composer.json if needed).
   • Test with PHPStan:

     vendor/bin/phpstan analyse --generate-mock-files
     

   • Confirm IDE autocompletion reflects new methods.
4. Full Rollout:
   • Commit stubs to version control (if static) or document CI/CD steps for dynamic generation.
   • Update CI pipelines to include stub generation (e.g., composer install --no-dev && composer install).

Compatibility

• Laravel Versions: No direct version constraints, but stubs must align with Laravel’s autoloading (PSR-4).
• PHP Versions: Follows Composer’s PHP version constraints (likely 8.0+).
• Tooling Conflicts:
  • Avoid conflicts with phpstan/extension-installer by ensuring stub paths don’t overlap.
  • If using rubix/mls, coordinate stub generation to prevent duplication.

Sequencing

1. Pre-requisite: Ensure PHPStan or equivalent static analysis tool is configured.
2. Step 1: Install the Composer plugin.
3. Step 2: Define extension methods in berry-method-extensions.json.
4. Step 3: Generate stubs via composer install.
5. Step 4: Integrate stubs into static analysis (PHPStan/Psalm) and IDEs.
6. Step 5: Document the process for onboarding new developers.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Stubs are generated automatically during dependency updates.
  • No runtime maintenance required.
• Dependency Updates:
  • If Berry dependencies update, regenerate stubs (composer update).
  • Monitor for breaking changes in the stub generator (e.g., format changes in berry-method-extensions.json).
• Customization:
  • Updating berry-method-extensions.json requires manual changes but no redeployment.

Support

• Developer Onboarding:
  • Document the stub generation process in CONTRIBUTING.md or README.md.
  • Highlight that IDEs must be configured to recognize stub files (e.g., PHPStorm’s "File Watchers").
• Troubleshooting:
  • Common issues:
    • Stubs not generating: Verify berry-method-extensions.json exists and is valid.
    • IDE not recognizing stubs: Check file paths and IDE settings.
    • PHPStan ignoring stubs: Ensure extension-classes is configured or stubs are in vendor/ with correct naming.
• Fallback: If stubs fail, revert to manual stub files or disable the plugin.

Scaling

• Performance: Zero impact on runtime or API performance.
• Large Codebases:
  • Stub generation time scales with the number of dependencies (negligible for most projects).
  • For monorepos, consider scoping berry-method-extensions.json to relevant packages.
• Distributed Teams:
  • Stubs can be committed to version control to avoid regeneration inconsistencies.
  • Alternatively, use a CI step to generate stubs before testing.

Failure Modes

Ramp-Up

• For Developers:
  • Time to Benefit: Immediate for static analysis;