Phpstan Rules Wrapper Laravel Package

Getting Started

Minimal Setup

1. Install the package:

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

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

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

   vendor/bin/phpstan analyse
   

   The package automatically includes 10+ popular PHPStan rule sets (e.g., phpstan/phpunit, symplify/phpstan-extensions, shipmonk/dead-code-detector).

3. Where to Look First:

   • Check your phpstan.neon (or phpstan.dist.neon) for pre-configured rules.
   • Review the included rulesets to understand what’s enabled by default.

Implementation Patterns

Daily Workflow

1. Integrate with CI/CD: Add PHPStan to your GitHub Actions/GitLab CI:

   - name: PHPStan
     run: vendor/bin/phpstan analyse --level=max
   

   Use --level=max for strict checks or --level=5 for a balanced approach.

2. Customize Rules: Extend phpstan.neon to override defaults:

   includes:
       - vendor/wyrihaximus/phpstan-rules-wrapper/phpstan.neon
       - phpstan-custom.neon  # Your overrides
   
   services:
       phpstan.rules.files:
           - app/**/*.php
           - tests/**/*.php
   

3. Targeted Analysis: Run PHPStan on specific files/directories:

   vendor/bin/phpstan analyse src/Service --level=7
   

4. Dead Code Detection: Use shipmonk/dead-code-detector (included) to find unused code:

   vendor/bin/phpstan analyse --enable=deadCode
   

Advanced Patterns

• Mockery/Unit Test Rules: Enable phpstan-mockery for better mock analysis:

  services:
      phpstan.parallel:
          enabled: true  # Speed up analysis
  

• Strict Rules: Combine with phpstan-strict-rules for stricter type checks:

  vendor/bin/phpstan analyse --level=9
  

• Deprecation Warnings: Use phpstan-deprecation-rules to catch deprecated APIs:

  vendor/bin/phpstan analyse --enable=deprecation
  

Gotchas and Tips

Common Pitfalls

1. Rule Conflicts:

   • Some rules (e.g., ergebnis.noPhpstanIgnore) are disabled by default due to conflicts. Check the release notes for disabled rules.
   • Fix: Explicitly enable/disable rules in phpstan.neon:

     services:
         phpstan.rules:
             ergebnis.noPhpstanIgnore: false
     

2. Performance:

   • The wrapper includes many rules, which can slow down analysis.
   • Tip: Use --parallel for faster runs:

     vendor/bin/phpstan analyse --parallel
     

3. PHP Version Requirements:

   • Requires PHP 8.4+ (since v12.0.0). Ensure your environment matches.

4. Vendor Directory:

   • The package does not commit the vendor directory (see PR #200). Ensure your .gitignore includes:

     vendor/
     

Debugging Tips

• Isolate Rule Issues: Run PHPStan with a single ruleset to debug:

  vendor/bin/phpstan analyse --rules-set=phpstan/phpstan-phpunit
  

• Check Rule Sources: Use --debug to see which rules are being applied:

  vendor/bin/phpstan analyse --debug
  

• Override Specific Rules: Disable problematic rules temporarily:

  services:
      phpstan.rules:
          shipmonk.deadCode: false  # Disable dead code detection
  

Extension Points

1. Add Custom Rulesets: Extend the wrapper by adding your own rules to composer.json:

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

2. Update Rulesets: The package uses Renovate for dependency updates. Monitor releases for breaking changes.

3. PHPStan Configuration: Merge custom phpstan.neon with the wrapper’s defaults:

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