Generator Laravel Package

Getting Started

Minimal Steps for Laravel Developers

1. Install the Package Add to your project via Composer:

   composer require --dev php-stubs/generator
   

   Why --dev? Stubs are a development tool, not runtime dependency.

2. First Use Case: Stub a Vendor Library Generate stubs for a third-party package (e.g., monolog/monolog) in vendor/:

   ./vendor/bin/generate-stubs vendor/monolog/monolog --out=stubs/monolog.stub.php
   

   Use case: Enable IDE autocompletion and PHPStan analysis for untyped libraries.

3. Where to Look First

   • Command Line: Run ./vendor/bin/generate-stubs --help for options.
   • Laravel-Specific: Focus on:
     • app/ (custom logic)
     • vendor/ (third-party packages)
     • config/ (global variables like config('app.timezone'))

Implementation Patterns

Workflows in Laravel Projects

1. Onboarding New Developers

• Pattern: Generate stubs for legacy Laravel modules (e.g., old Eloquent models without PHPDoc).
• Example:

  ./vendor/bin/generate-stubs app/Models --out=stubs/app-models.stub.php --include=Classes,Functions
  

• Integration:
  • Place stubs in stubs/ (version-controlled).
  • Configure IDE to load stubs (e.g., PhpStorm: File > Settings > PHP > Include Paths).

2. Static Analysis with PHPStan

• Pattern: Use stubs to reduce false positives in PHPStan.
• Example:

  ./vendor/bin/generate-stubs vendor/laravel/framework --out=stubs/framework.stub.php
  phpstan analyse app --level=max --generate-baseline
  

• Tip: Combine with phpstan/extension-installer to auto-load stubs.

3. CI/CD Pipeline

• Pattern: Validate stubs in CI to catch breaking changes.
• Example (GitHub Actions):

  - name: Generate and validate stubs
    run: |
      ./vendor/bin/generate-stubs app/ vendor/ --out=stubs/all.stub.php
      php -r "require 'stubs/all.stub.php'; echo 'Stub generation successful';"
  

4. Dynamic Laravel Features

• Pattern: Stub Facades, Macros, or dynamic methods (e.g., Str::of()).
• Example:

  ./vendor/bin/generate-stubs vendor/laravel/framework/src/Illuminate/Support --out=stubs/illuminate.stub.php --include=Classes,Functions
  

• Gotcha: Laravel’s runtime method resolution (e.g., Str::macro()) may require manual stub adjustments.

5. Partial Stubs for Performance

• Pattern: Generate stubs only for critical paths (e.g., API controllers).
• Example:

  ./vendor/bin/generate-stubs app/Http/Controllers --out=stubs/controllers.stub.php --include=Classes
  

Integration Tips

Laravel-Specific

1. Stub Facades and Helpers Use --include=Functions to capture Laravel’s global helpers (e.g., route(), view()):

   ./vendor/bin/generate-stubs vendor/laravel/framework/src/Illuminate/Support/helpers.php --out=stubs/helpers.stub.php
   

2. Service Provider Stubs Stub register()/boot() methods to enable IDE navigation in AppServiceProvider:

   ./vendor/bin/generate-stubs app/Providers --out=stubs/providers.stub.php
   

3. Eloquent Relationships Generate stubs for dynamic relationships (e.g., hasManyThrough) to improve IDE support:

   ./vendor/bin/generate-stubs app/Models --out=stubs/eloquent.stub.php --include=Classes
   

Tooling

1. PHPStan Extension Install phpstan/extension-installer to auto-load stubs:

   composer require --dev phpstan/extension-installer
   

   Configure phpstan.neon:

   includes:
     - stubs/
   

2. PhpStorm Configuration

   • Go to File > Settings > PHP > Include Paths.
   • Add stubs/ as a mapped path for your project.

3. VSCode (Intelephense) Add to .vscode/settings.json:

   {
     "intelephense.environment.php.get": {
       "stubs": ["stubs/**/*.stub.php"]
     }
   }
   

Gotchas and Tips

Pitfalls

1. False Positives in Static Analysis

   • Issue: Stubs may over-approximate types, causing PHPStan/Psalm to flag false errors.
   • Fix: Use --nullify-globals to avoid stubbing uninitialized globals:

     ./vendor/bin/generate-stubs app/ --out=stubs/app.stub.php --nullify-globals
     

   • Workaround: Configure PHPStan to ignore stub-specific issues:

     arguments.rules.*.level = 'ignore'
     

2. Dynamic Class Loading

   • Issue: Laravel’s runtime class generation (e.g., Facades, Proxies) may not be fully captured.
   • Fix: Manually stub critical classes or use --visitor for custom parsing:

     ./vendor/bin/generate-stubs vendor/laravel/framework --visitor=CustomVisitor
     

3. Duplicate Stubs

   • Issue: Generating stubs for the same class multiple times (e.g., from app/ and vendor/).
   • Fix: Use --deduplicate (if available) or merge stubs manually.

4. IDE-Specific Quirks

   • PhpStorm: May ignore stubs if not marked as "Resources Root".
   • VSCode: Requires Intelephense for stub support (native PHP extension lacks stub parsing).

5. Performance

   • Issue: Large codebases (e.g., Laravel + vendors) may slow down stub generation.
   • Fix: Generate stubs incrementally (e.g., only app/ in development, vendor/ in CI).

Debugging Tips

1. Validate Stubs Use PHP’s token_get_all() to verify stub syntax:

   $stubCode = file_get_contents('stubs/app.stub.php');
   token_get_all($stubCode); // Should not throw errors
   

2. Compare with Original Diff stubs against the original code to spot missing or incorrect declarations:

   diff -u <(grep -A 5 "function foo" app/OriginalFile.php) <(grep -A 5 "function foo" stubs/app.stub.php)
   

3. Log Parsing Errors Enable verbose output to debug parsing issues:

   ./vendor/bin/generate-stubs app/ --verbose
   

Extension Points

1. Custom Visitors Extend stub generation with a custom StubsGenerator\Visitor for Laravel-specific logic (e.g., stubbing Route::macro() calls):

   use StubsGenerator\{StubsGenerator, Visitor\NodeVisitor};
   
   class LaravelMacroVisitor extends NodeVisitor {
       public function enterNode() { /* Custom logic */ }
   }
   
   $generator = new StubsGenerator();
   $generator->addVisitor(new LaravelMacroVisitor());
   

2. Post-Processing Stubs Use PHP’s php -r to filter or transform stubs after generation:

   ./vendor/bin/generate-stubs app/ --out=stubs/raw.stub.php && \
   php -r "file_put_contents('stubs/filtered.stub.php', preg_replace('/@deprecated/', '', file_get_contents('stubs/raw.stub.php')));"
   

3. Git Hooks for Stub Sync Automate stub updates with a pre-commit hook:

   echo '#!/bin/bash
   ./vendor/bin/generate-stubs app/ --out=stubs/app.stub.php
   git add stubs/app.stub.php
   ' > .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

Laravel-Specific Quirks

1. Stubbing config() and env() Globals like config('app.timezone') may not stub correctly. Use --nullify-globals or manually stub:

   // Manually add to stubs.php
   /** @var string */
   $appTimezone = null;