Hidev Phpstan Laravel Package

Getting Started

Minimal Setup

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

   composer require hiqdev/hidev-phpstan
   

   Ensure hiqdev/hidev is also installed (required dependency).

2. Configure HiDev Add the PHPStan extension to your hidev.json:

   {
       "extensions": [
           "hiqdev/hidev-phpstan"
       ]
   }
   

3. Basic Usage Run PHPStan checks via HiDev CLI:

   hidev phpstan
   

   This executes PHPStan with default configurations (located in phpstan.neon or phpstan.dist.neon).

First Use Case: Integrating PHPStan into Laravel Workflow

• Trigger on Git Hooks Add to .git/hooks/pre-commit:

  #!/bin/bash
  hidev phpstan --level=5 --memory-limit=1G
  

  (Adjust --level for strictness, e.g., 5 for maximum.)

• CI/CD Pipeline Use in GitHub Actions or GitLab CI:

  # .github/workflows/phpstan.yml
  jobs:
    phpstan:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
        - run: composer install
        - run: hidev phpstan --error-format=github
  

Implementation Patterns

Workflow Integration

1. Custom PHPStan Config Extend phpstan.neon (or phpstan.dist.neon) to include Laravel-specific rules:

   includes:
       - vendor/laravel/framework/src/Illuminate/*
   
   parameters:
       level: 7
       checkMissingIterableValueType: true
       checkReturnTypeInConstructor: true
   

2. Parallel Execution Leverage HiDev’s parallel task support:

   hidev phpstan --parallel --processes=4
   

   (Useful for large codebases.)

3. Autofix Mode Combine with --generate-baseline for iterative fixes:

   hidev phpstan --generate-baseline=phpstan.baseline.neon
   git add phpstan.baseline.neon
   

Laravel-Specific Patterns

• Service Provider Hooks Dynamically load PHPStan rules in AppServiceProvider:

  use HiQDev\Hidev\PHPStan\PHPStanExtension;
  
  public function boot()
  {
      $this->app->make(PHPStanExtension::class)->registerRules();
  }
  

• Dynamic Configuration Use Laravel’s config to override PHPStan settings:

  // config/hidev.php
  'phpstan' => [
      'level' => env('PHPSTAN_LEVEL', 5),
      'paths' => [
          app_path('Http/Controllers'),
          database_path('Factories'),
      ],
  ],
  

  Then reference in phpstan.neon:

  parameters:
      paths:
          - %config.hidev.phpstan.paths%
  

Gotchas and Tips

Common Pitfalls

1. Configuration Overrides

   • Issue: phpstan.neon in root dir may conflict with Laravel’s cached configs.
   • Fix: Use phpstan.dist.neon as a template and symlink to bootstrap/cache/:

     ln -s phpstan.dist.neon bootstrap/cache/phpstan.neon
     

2. Memory Limits

   • Issue: PHPStan crashes on large projects with default memory_limit.
   • Fix: Increase via CLI or php.ini:

     hidev phpstan --memory-limit=2G
     

     Or in phpstan.neon:

     parameters:
         memoryLimit: "2G"
     

3. HiDev Cache Invalidation

   • Issue: Changes to hidev.json or PHPStan config aren’t reflected.
   • Fix: Clear HiDev cache:

     hidev clear-cache
     

Debugging Tips

• Verbose Output Enable debug mode for detailed logs:

  hidev phpstan --verbose
  

• Isolated Testing Test specific files/directories:

  hidev phpstan app/Http/Controllers/UserController.php
  

• Baseline Management

  • Warning: Committing phpstan.baseline.neon may hide legitimate errors.
  • Best Practice: Use .gitignore for local baselines and share only critical ones.

Extension Points

1. Custom Rules Extend PHPStan’s rule set by creating a rules.neon file:

   includes:
       - vendor/bin/ruleset.neon
   

   Reference in phpstan.neon:

   parameters:
       rules:
           - rules.neon
   

2. HiDev Events Listen to phpstan.run events in EventServiceProvider:

   protected $listen = [
       'HiQDev\Hidev\PHPStan\Events\PHPStanRun' => [
           App\Listeners\LogPHPStanResults::class,
       ],
   ];
   

3. Parallel Task Limits Adjust --processes based on server resources (default: 4). Monitor with:

   hidev phpstan --profile