Phpstan Strict Rules Laravel Package

Technical Evaluation

Architecture Fit: The package extends PHPStan’s static analysis capabilities, aligning perfectly with Laravel’s PHP-centric stack. It enforces best practices (e.g., exception handling, superglobal avoidance) without runtime overhead, making it ideal for CI/CD-driven quality gates. The rules are framework-agnostic but particularly relevant for Laravel’s dependency injection and PSR-7 request patterns.

Integration Feasibility: Low technical debt for adoption—requires only Composer installation and phpstan.neon configuration. However, the 2021 release date and PHPStan 1.0+ compatibility (vs. Laravel’s typical PHPStan 0.x/1.x usage) introduce risks. The package’s focus on superglobals (e.g., $_GET, $_POST) directly conflicts with Laravel’s legacy Request facade usage, necessitating opt-outs or refactoring.

Technical Risk:

• Compatibility: Last release predates PHP 8.2+ features (e.g., enums, attributes) and PHPStan’s modern levels (6/7). Risk of false positives/negatives with Laravel’s dynamic properties or magic methods.
• Maintenance: No recent activity raises concerns about unpatched vulnerabilities (e.g., dependency better-reflection).
• Rule Overlap: Some rules (e.g., default in switch) may conflict with Laravel’s convention-heavy patterns (e.g., case in Illuminate\Support\Enum).

Key Questions:

1. PHPStan Version: Is the team using PHPStan 1.x or legacy 0.x? If 1.x, test compatibility with phpstan/extension-installer.
2. Laravel-Specific Exceptions: How to handle false positives for Laravel’s Request facade (e.g., $request->input() vs. $_GET)?
3. Performance Impact: Will the additional rules slow CI for large codebases (e.g., 10K+ files)?
4. Rule Prioritization: Which rules (e.g., exception handling vs. superglobals) should be enforced first?
5. Alternatives: Evaluate phpstan/extension-installer + custom rules for more control.

Integration Approach

Stack Fit:

• Laravel + PHPStan: Native fit for static analysis, but requires opt-outs for Laravel-specific patterns (e.g., Request facade, dynamic properties).
• CI/CD: Best deployed as a pre-commit hook (via phpstan --level=5) or GitHub Actions step with incremental enforcement.
• Legacy Code: Use --generate-baseline to exclude violations during transition.

Migration Path:

1. Phase 1 (Discovery):
   • Install with composer require --dev thecodingmachine/phpstan-strict-rules.
   • Configure phpstan.neon to include only non-breaking rules (e.g., exception handling, switch defaults).
   • Run locally (./vendor/bin/phpstan analyse) to identify critical violations.
2. Phase 2 (Incremental Enforcement):
   • Enable stricter rules (e.g., superglobals) in CI after fixing top 10% of violations.
   • Use @phpstan-ignore-next-line for temporary opt-outs (e.g., legacy controllers).
3. Phase 3 (Automation):
   • Integrate with roave/security-advisories to monitor dependency risks.
   • Explore phpstan/parallel-lint for faster analysis on large codebases.

Compatibility:

• PHPStan 1.x: Test with ^1.0 to avoid breaking changes (e.g., rule IDs).
• Laravel Workarounds:
  • Whitelist Illuminate\Http\Request methods in phpstan.neon:

    parameters:
        checkGenericClassInNonGenericContext: false
        checkPropertyTypeInNonObjectClass: false
    

  • Use @var annotations for dynamic properties (e.g., /** @var array<string, mixed> */).

Sequencing:

Operational Impact

Maintenance:

• Forking Risk: High due to inactivity; consider forking to add Laravel-specific exceptions (e.g., Illuminate\Database\Eloquent\Model dynamic properties).
• Dependency Updates: Monitor better-reflection for CVEs (e.g., CVE-2023-XXXX).
• Rule Tuning: Expect 1–2 hours/week to adjust rules for Laravel quirks (e.g., Collection methods).

Support:

• Developer Onboarding: Requires training on:
  • Rule rationales (e.g., "why forbid Exception?").
  • Opt-out patterns (@phpstan-ignore-line).
• Debugging: Limited community support; rely on:
  • PHPStan’s issue tracker.
  • Laravel-specific forks (e.g., spatie/phpstan-laravel).

Scaling:

• Performance: Rules add ~10–30% to analysis time. Mitigate with:
  • phpstan --memory-limit=1G for large projects.
  • Parallel analysis (phpstan/parallel-lint).
• CI Bottlenecks: Prioritize rule subsets (e.g., run exception rules separately).

Failure Modes:

Ramp-Up:

• Team Training:
  • Workshop: Demo rule violations on a sample Laravel app.
  • Cheat Sheet: Document common exceptions (e.g., Request facade workarounds).
• Documentation:
  • Update CONTRIBUTING.md with PHPStan rule examples.
  • Add a phpstan-rules.md to the repo explaining opt-outs.
• Onboarding Checklist:
  1. Install phpstan-strict-rules.
  2. Configure phpstan.neon with Laravel exceptions.
  3. Run phpstan analyse --level=5 locally.
  4. Fix top 5 violations before merging PRs.