Phpstan Rules Laravel Package

Getting Started

Begin by installing the package via Composer:

composer require --dev symplify/phpstan-rules

Then, enable the rules in your phpstan.neon file. Start with the rules section to selectively activate rules—e.g., for stricter object construction, null safety, or naming conventions:

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

A first practical use case: catch cases where developers accidentally inject services via constructor and @inject annotations (a common anti-pattern in legacy Symfony code). Enable UninjectServiceAnnotationRule to auto-detect this. Run phpstan once—issues will surface quickly in Controllers or Services.

Implementation Patterns

• Granular Rule Activation: Instead of auto-including all rules, create custom phpstan.neon configs (e.g., rules/best-practices.neon, rules/security.neon) to evolve rule adoption per team maturity.
• CI Enforcement: Add vendor/bin/phpstan to your pipeline. Fail builds if risky rules (e.g., NoMagicPullRule, NoDirectServiceAccessRule) are violated—prevents runtime bugs from leaking.
• Gradual Rollout: For large codebases, enable rules with level hints (e.g., maxLevel: 5) or use ignoreErrors to suppress legacy violations while catching new ones.
• Laravel Integration: Pair with Laravel’s built-in PHPStan support (e.g., via nunomaduro/larastan)—this package complements framework-specific rules with broader PHP-level checks like NoSuperfluousExtendsRule or NoUnneededFqcnInPhpDocRule.

Gotchas and Tips

• Silent Failures: Rules do not run unless explicitly included in phpstan.neon. Double-check includes and neon syntax (YAML is whitespace-sensitive).
• Naming Conflicts: Some rules (e.g., NoUnusedPrivateMethodRule) overlap with PHPStan’s core. Prioritize this package’s versions only if they offer stricter semantics—review rule ids in the config file.
• Performance: Enabling all rules (~40+) may slow analysis. Profile with --memory-limit=2G and disable rarely needed rules (e.g., NoInlineDocCommentRule).
• Extension Points: Custom logic can extend rules by extending base classes (e.g., AbstractSymplifyRule) in your own PHPStan extension—useful for project-specific constraints like App\Dto\* naming.
• Documentation Gap: GitHub docs are sparse—read rule names in config/rules.neon or source (src/Rules/) to understand semantics. Use --debug flag to trace which rule flagged an error.