Phpstan Extensions Laravel Package

Product Decisions This Supports

• Enforcing Code Quality & Consistency: Adopting this package enables stricter static analysis for PHP projects, aligning with initiatives to improve maintainability, readability, and adherence to best practices (e.g., PSR standards, framework-specific conventions).
• Framework-Specific Enforcement: Supports roadmap items targeting Symfony, Yii, or other PHP frameworks by enforcing framework-specific best practices (e.g., discouraging raw filesystem calls in Symfony projects).
• Build vs. Buy: A "buy" decision for teams already using PHPStan, as it extends existing tooling without reinventing core static analysis. Reduces reliance on custom scripts or manual reviews for common anti-patterns.
• Security & Maintainability: Directly addresses technical debt by catching issues like:
  • Unused variables (reducing cognitive load).
  • Hardcoded class strings (risk of typos/breaks).
  • Raw date/time calls (security/maintainability risks).
  • Anti-patterns like singletons in models (Yii/Symfony).
• Onboarding & Developer Experience: Lowers barriers for new contributors by automating enforcement of team conventions (e.g., Interface suffixes, Abstract prefixes).
• Migration to Modern Practices: Supports gradual adoption of abstractions (e.g., lcobucci/clock for time handling) by flagging legacy patterns.

When to Consider This Package

• Not for Greenfield Projects: If your codebase is already compliant with all rules, the incremental value may be low. Prioritize where technical debt is highest.
• Non-PHP Projects: Irrelevant for non-PHP stacks (e.g., Node.js, Python).
• Teams Without PHPStan: Requires existing PHPStan adoption; otherwise, setup friction outweighs benefits.
• Custom Rule Needs: If your team has highly specialized rules, this package may not cover them (though it’s extensible).
• Performance-Critical Paths: Some rules (e.g., UnusedVariableRule) add static analysis overhead. Benchmark impact if running in CI/CD.
• Legacy Codebases with High False Positives: May require significant configuration tuning to avoid noise. Test thoroughly before enforcing.
• Alternative Tools Exist: For some use cases (e.g., dependency injection validation), dedicated tools like phpstan/phpstan-doctrine may suffice.

How to Pitch It (Stakeholders)

For Executives:

"This package supercharges our PHP code quality by automating enforcement of best practices—like catching unused variables, preventing raw filesystem calls in Symfony, and discouraging anti-patterns like singletons in models. It’s a low-cost, high-impact way to reduce bugs, improve maintainability, and align with modern PHP frameworks. Think of it as a ‘linter on steroids’ that pays for itself by catching issues early, before they hit production. The setup is minimal (just a Composer install), and it integrates seamlessly with our existing PHPStan workflow."

For Engineering Teams:

*"We’re adding slam/phpstan-extensions to:

1. Catch subtle bugs early: Unused variables, hardcoded class strings, and raw date/time calls are now automatically flagged.
2. Enforce framework conventions: Symfony/Yii-specific rules (e.g., forbidding raw filesystem calls) will standardize our codebase.
3. Reduce tech debt: Rules like ::class enforcement and singleton restrictions in models prevent future refactoring pain.
4. Gradual adoption: Start with --level 5 in CI, then enforce stricter levels as the team adapts.

Why now?

• Minimal setup (works with existing PHPStan).
• Proven in production (used by [X] teams).
• Aligns with our roadmap to modernize PHP practices.

Next steps:

• Add to composer.json (dev dependency).
• Configure in phpstan.neon (or use extension-installer).
• Run locally first, then enforce in CI.

Impact: Fewer production bugs, faster onboarding, and code that’s easier to maintain."*