Phpstan Rules Laravel Package

Getting Started

1. Install the package via Composer: composer require --dev sanmai/phpstan-rules
2. Include its config in your phpstan.neon (or phpstan.dist.neon):

   includes:
       - vendor/sanmai/phpstan-rules/config/rules.neon
   

3. Run PHPStan: vendor/bin/phpstan analyze – the new rules will apply alongside core PHPStan checks.
4. First use case: Catch accidental use of die/exit in library code or detect missing @return annotations on public methods — both now flagged with high severity.

Implementation Patterns

• CI Integration: Add phpstan as a step in your CI pipeline; this package’s rules are tuned to fail builds on real anti-patterns (e.g., unhandled __destruct() exceptions, dynamic property access), not style.
• Progressive Enabling: Start with lower error levels (e.g., level: 5), then gradually increase to 7 or 8 as issues are fixed — the package provides fine-grained rule control via config overrides.
• Custom Extension: Override or disable specific rules by re-declaring them in your config:

  services:
      -
          class: Sanmai\PHPStan\Rules\NoExitRule
          tags: [phpstan.rules.rule]
  

• Combined with Laravel (if applicable): Use alongside Laravel-specific extensions (e.g., laravel-phpstan); this package focuses on PHP semantics, not framework conventions.

Gotchas and Tips

• Rule Clashes: Some rules (e.g., NoDirectOutputRule) may conflict with Laravel’s dump() usage in development — exclude specific paths via parameters.ignoreErrors.
• PHP Version Compatibility: Ensure PHP version in parameters.phpVersion matches your runtime; rules like NoNamedArgumentReorderingRule rely on accurate version info.
• Debugging False Positives: Use --debug flag to see which rule triggered the error — check source comments for exceptions (e.g., some rules allow exit in CLI entrypoints).
• Performance Impact: Minimal (rules are tree-shaken), but if using a very large codebase, consider narrowing paths in phpstan.neon — the package itself adds near-zero overhead.
• Extension Point: Want your own rules? This package is designed to be forked — its rule classes follow the same pattern as phpstan/phpstan-src, making it easy to copy and adapt patterns.