Php 8 Stubs Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require --dev phpstan/php-8-stubs
   

   Add the stubs directory to your PHPStan configuration (phpstan.neon):

   includes:
       - vendor/phpstan/php-8-stubs/src/
   

2. Configure PHP Version: Specify your PHP version in phpstan.neon to ensure correct stubs are loaded:

   parameters:
       phpVersionId: 80300  # Example: PHP 8.3.0
   

3. First Use Case: Run PHPStan on a Laravel controller or service to validate type correctness:

   vendor/bin/phpstan analyse app/Http/Controllers/
   

   Focus on catching undefined methods, incorrect return types, or deprecated functions.

Implementation Patterns

Core Workflows

1. Version-Aware Analysis: Use Php8StubsMap to dynamically load stubs for specific PHP versions (e.g., in CI or multi-version projects):

   $map = new \PHPStan\Php8StubsMap(80300); // PHP 8.3.0
   $stubPath = $map->classes['datetime'] ?? null; // Path to DateTime stub
   

2. Laravel-Specific Integration:

   • Service Providers: Extend stubs for custom classes (e.g., App\Services\PaymentService) by creating manual stubs in stubs/ and including them in phpstan.neon:

     includes:
         - stubs/
     

   • Dynamic Properties: Use @var annotations in PHPDoc blocks for Laravel’s dynamic properties (e.g., stdClass in facades):

     /** @var stdClass $data */
     public function handle($data) { ... }
     

3. CI/CD Pipeline: Add PHPStan to your GitHub Actions/GitLab CI with stubs enabled:

   - name: Run PHPStan
     run: vendor/bin/phpstan analyse --level=max app/ --memory=1G
   

Laravel-Specific Tips

• Facade Methods: Stub Laravel facades (e.g., Auth, Cache) by extending phpstan.neon:

  parameters:
      stubFiles:
          - vendor/laravel/framework/src/Illuminate/Foundation/Application.php.stub
  

  (Generate stubs using phpstan/extension-installer or manually.)

• Dynamic Return Types: Use union types for Laravel’s polymorphic methods (e.g., Model::find()):

  /** @return \Illuminate\Database\Eloquent\Model|\Illuminate\Database\Eloquent\Collection|null */
  public function findUser($id) { ... }
  

• Testing: Run PHPStan against Laravel’s test suite to validate stub accuracy:

  vendor/bin/phpstan analyse tests/ --level=max
  

Gotchas and Tips

Pitfalls

1. Version Mismatch:

   • Issue: Running PHPStan with stubs for PHP 8.3.0 on a PHP 8.0.0 project causes false positives/negatives.
   • Fix: Always match phpVersionId to your runtime PHP version. Use php -r "echo PHP_VERSION_ID;" to verify.

2. False Positives in Legacy Code:

   • Issue: Laravel’s magic methods (e.g., __get(), __call()) or dynamic properties (e.g., stdClass) trigger errors.
   • Fix:
     • Suppress warnings with @phpstan-ignore-next-line or @phpstan-ignore-line.
     • Extend stubs for custom classes (e.g., create stubs/App/Models/User.stub).

3. Performance Overhead:

   • Issue: Large codebases slow down analysis.
   • Fix:
     • Exclude directories in phpstan.neon:

       excludeFiles:
           - 'vendor/'
           - 'tests/'
       

     • Use --parallel and --memory=2G for CI.

4. IDE Conflicts:

   • Issue: PHPStorm/VSCode may ignore stubs or show incorrect autocompletion.
   • Fix:
     • Ensure IDEs use the same PHPStan config (phpstan.neon).
     • Restart IDE after adding stubs or run phpstan:generate-baseline.

5. Deprecated Features:

   • Issue: Stubs may flag deprecated PHP functions (e.g., create_function) as errors.
   • Fix: Adjust PHPStan’s level or suppress specific warnings:

     rules:
         PHPStan\Rules\DeprecatedFunctionRule: disabled
     

Debugging Tips

• Inspect Stub Coverage: Use Php8StubsMap to verify loaded stubs:

  $map = new \PHPStan\Php8StubsMap(80300);
  print_r($map->classes); // Check if critical classes (e.g., 'datetime') are present.
  

• Generate Baselines: Create a baseline for existing code to avoid overwhelming teams:

  vendor/bin/phpstan analyse --generate-baseline app/
  

  Commit baseline.neon to version control.

• Isolate Issues: Run PHPStan on a single file to debug:

  vendor/bin/phpstan analyse app/Http/Controllers/UserController.php
  

Extension Points

1. Custom Stubs: Create stubs for Laravel-specific classes (e.g., App\Contracts\PaymentGateway) in stubs/ and include them in phpstan.neon:

   includes:
       - stubs/
   

2. PHPStan Extensions: Write custom PHPStan rules to handle Laravel patterns (e.g., dynamic facades):

   // Example: Extend PHPStan to ignore Laravel's __call magic methods
   final class LaravelMagicMethodRule extends Rule
   {
       public function getNodeType(): string { return 'method'; }
       public function processNode(Node $node): array { ... }
   }
   

3. Version-Specific Logic: Use Php8StubsMap to conditionally load stubs based on PHP version in CI:

   $phpVersionId = getenv('PHP_VERSION_ID') ?? 80000; // Default to PHP 8.0.0
   $map = new \PHPStan\Php8StubsMap($phpVersionId);
   

Laravel-Specific Quirks

• Dynamic Facades: Stub facades by extending Illuminate\Support\Facades\Facade in phpstan.neon:

  parameters:
      stubFiles:
          - stubs/Facades.stub
  

  Example Facades.stub:

  <?php
  namespace Illuminate\Support\Facades;
  
  class Auth extends \Illuminate\Auth\AuthManager { ... }
  

• Blade Templates: Exclude Blade files from strict analysis (they’re pre-processed):

  excludeFiles:
      - 'resources/views/**'
  

• Service Container: For type hints in service bindings, use @mixin in PHPDoc:

  /** @mixin \Illuminate\Contracts\Auth\Factory */
  class AuthServiceProvider extends ServiceProvider { ... }