Phpstan Rules Wrapper Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev wyrihaximus/phpstan-rules-wrapper
   

   This leverages phpstan/extension-installer under the hood, so no additional configuration is required in phpstan.neon.

2. First Use Case: Run PHPStan with the default configuration:

   vendor/bin/phpstan analyse
   

   The package automatically integrates 10+ PHPStan rule sets (e.g., phpstan/phpstan-strict-rules, symplify/phpstan-extensions, shipmonk/dead-code-detector).

3. Where to Look First:

   • Check phpstan.neon for any existing rules (none needed for this package).
   • Review the included rulesets to understand what’s enabled by default.

Implementation Patterns

Usage Patterns

1. Zero-Configuration Integration:

   • The package is designed to work out-of-the-box. No manual rule imports or includes are required in phpstan.neon.
   • Ideal for teams wanting pre-configured, opinionated static analysis without managing individual rule dependencies.

2. Customizing Rules:

   • Override default rules by extending phpstan.neon:

     includes:
         - vendor/wyrihaximus/phpstan-rules-wrapper/phpstan.neon
     rules:
         Shipmonk\DeadCodeDetector\DeadCodeDetectorRule: false  # Disable dead code detection
         PHPStan\StrictRules\StrictPropertyTypeRule: true     # Explicitly enable strict rules
     

   • Use extends to inherit and modify:

     extends:
         - vendor/wyrihaximus/phpstan-rules-wrapper/phpstan.neon
     

3. CI/CD Workflows:

   • Integrate into GitHub Actions, GitLab CI, or Laravel’s phpunit.xml:

     <phpunit>
         <phpstan>
             <config>phpstan.neon</config>
             <autoload>
                 <file>vendor/autoload.php</file>
             </autoload>
         </phpunit>
     </phpunit>
     

   • Run in parallel for large codebases:

     vendor/bin/parallel-lint --phpstan --workers=4
     

4. Laravel-Specific Use Cases:

   • Service Container Analysis: Use symplify/phpstan-extensions (included) to analyze Laravel’s bind(), singleton(), and tag() methods:

     services:
         - Symplify\PHPStanExtensions\Services\Container\ContainerService
     

   • Route/Controller Validation: Combine with phpstan/phpstan-phpunit to validate route parameters and controller methods.

5. Dead Code Detection:

   • Leverage shipmonk/dead-code-detector to find unused:
     • Properties/methods in production code (ignores test files by default).
     • Example: Detect dead code in app/Models/User.php:

       vendor/bin/phpstan analyse --level=max --no-progress-bar
       

Workflows

1. Onboarding New Developers:

   • Add the package to composer.json and run composer install. No additional setup required.
   • Document the default rule sets in your team’s static analysis guide.

2. Refactoring Sessions:

   • Use phpstan/phpstan-strict-rules to catch type inconsistencies during refactoring.
   • Example: Convert loose array types to strict generics:

     // Before
     public function getUsers(): array { ... }
     
     // After (with strict rules)
     public function getUsers(): array<User> { ... }
     

3. Deprecation Management:

   • phpstan/phpstan-deprecation-rules flags deprecated Laravel methods (e.g., Route::resource() vs. Route::apiResource()).
   • Example output:

     [ERROR]  Method Illuminate\Routing\Router::resource() is deprecated since Laravel 9.0.
     

Integration Tips

• Combine with rector: Use symplify/phpstan-extensions (included) to auto-fix issues with Rector:

  vendor/bin/rector process src --dry-run
  

• Exclude Directories: Override parameters.excludePaths in phpstan.neon:

  parameters:
      excludePaths:
          - tests/
          - database/
  

• Custom Rule Sets: Add your own rules to the wrapper’s phpstan.neon by extending it:

  extends:
      - vendor/wyrihaximus/phpstan-rules-wrapper/phpstan.neon
  rules:
      - YourVendor\YourRules\YourRule
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts:

   • Some rules (e.g., ergebnis.noPhpstanIgnore) are disabled by default due to conflicts with Laravel’s .phpstan.ignore files.
   • Fix: Explicitly enable/disable in phpstan.neon:

     rules:
         Ergebnis\PhpStanRules\Rules\NoPhpstanIgnoreRule: false
     

2. Performance Overhead:

   • Rule sets like type-coverage or dead-code-detector can slow down analysis.
   • Tip: Run them separately or in CI:

     vendor/bin/phpstan analyse --level=max --memory-limit=2G
     

3. PHP Version Requirements:

   • The package requires PHP 8.4+ (check composer.json).
   • Workaround: Use a lower version of the wrapper if needed (e.g., 12.x for PHP 8.1).

4. False Positives:

   • phpstan-mockery may flag legitimate Mockery usage.
   • Fix: Adjust Mockery’s mockery.directMockingAllowed in phpstan.neon:

     services:
         - PHPStan\Mockery\MockeryService
     parameters:
         mockery:
             directMockingAllowed: true
     

5. Vendor Directory Bloat:

   • The wrapper installs ~10+ dependencies, increasing vendor/ size.
   • Tip: Use composer install --prefer-dist to optimize disk usage.

Debugging

1. Isolate Rule Issues:

   • Run PHPStan with a single rule set to debug:

     vendor/bin/phpstan analyse --level=max --rules=PHPStan\StrictRules\*
     

   • Use --error-format=json for machine-readable output:

     vendor/bin/phpstan analyse --error-format=json > errors.json
     

2. Check Rule Compatibility:

   • Verify rule versions in composer.lock match the wrapper’s dependencies.
   • Example: Ensure symplify/phpstan-extensions is ^10.0 for Laravel 10.x.

3. Disable All Rules:

   • Temporarily disable all wrapper rules to test custom configurations:

     rules:
         *: false
     

Configuration Quirks

1. Neon File Location:

   • The wrapper’s rules are loaded from vendor/wyrihaximus/phpstan-rules-wrapper/phpstan.neon.
   • Tip: Symlink this file to a custom location for easier overrides:

     ln -s vendor/wyrihaximus/phpstan-rules-wrapper/phpstan.neon config/phpstan-wrapper.neon
     

2. Level-Specific Rules:

   • Some rules (e.g., strict-rules) are level-dependent (e.g., --level=max).
   • Tip: Define levels in phpstan.neon:

     levels:
         project:
             rules:
                 - PHPStan\StrictRules\*
     

3. Laravel-Specific Rules:

   • symplify/phpstan-extensions may flag Laravel’s magic methods (e.g., __get(), __set()).
   • Fix: Exclude Laravel core files:

     parameters:
         excludePaths:
             - vendor/laravel/
     

Extension Points

1. Add Custom Rulesets:

   • Extend the wrapper’s composer.json to include additional rules:

     "extra": {
         "phpstan-rules-wrapper": {
             "custom-rules": ["vendor/package/rules.neon"]
         }
     }
     

   • Note: Requires custom logic to merge rules (not natively supported).

2. Override Individual Rules:

   • Use parameters.rules to fine-tune included rulesets:

     parameters:
         rules:
             Shipmonk\DeadCodeDetector\