Phpstan Rules Laravel Package

Product Decisions This Supports

• Enhanced Code Quality & Maintainability: Adopting this package enables stricter static analysis, reducing runtime errors and improving developer productivity by catching edge cases early (e.g., unsafe comparisons, unchecked exceptions, or mutable public properties).
• Roadmap Alignment with PHP 8+ Features: Leverages modern PHP features (e.g., readonly, match, generics) to future-proof codebases, aligning with ShipMonk’s own strict PHPStan configurations.
• Build vs. Buy: Buy for teams already using PHPStan and seeking to elevate their static analysis without reinventing custom rules. Avoids maintenance overhead of in-house solutions.
• Use Cases:
  • Legacy Code Modernization: Gradually enforce stricter rules (e.g., enforceNativeReturnTypehint, forbidCast) to migrate older codebases.
  • New Projects: Mandate from day one for greenfield projects to prevent anti-patterns (e.g., forbidCheckedExceptionInCallable).
  • Team Onboarding: Standardize coding practices across distributed teams by enforcing consistent rules (e.g., classSuffixNaming for class hierarchies).

When to Consider This Package

• Adopt if:

  • Your team already uses PHPStan and seeks additional strictness beyond default rules.
  • You prioritize immutability, type safety, or explicit error handling (e.g., checked exceptions).
  • Your codebase includes complex type hierarchies (e.g., enums, generics) or legacy patterns needing modernization.
  • You’re willing to invest in configuration (e.g., tuning forbidCast blacklists or classSuffixNaming mappings).

• Look Elsewhere if:

  • You’re not using PHPStan (this is a layer on top of PHPStan, not a standalone tool).
  • Your team lacks bandwidth to adjust existing code to meet ultra-strict rules (e.g., enforceReadonlyPublicProperty may break legacy classes).
  • You prefer minimalist static analysis—this package adds ~40 rules, which may be overkill for small projects.
  • Your PHP version is <8.0 (some rules, like readonly, are PHP 8.1+ only).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us catch critical bugs at development time—like unsafe type comparisons or unhandled exceptions—using ShipMonk’s battle-tested PHPStan rules. By adopting it, we’ll reduce production incidents from PHP edge cases (e.g., null comparisons, mutable public properties) while future-proofing our codebase for PHP 8+. The upfront effort to configure it pays off in long-term maintainability and faster onboarding for new engineers. Think of it as a ‘PHP linter on steroids’—no runtime surprises."

For Engineering Teams:

*"This gives us ShipMonk’s strict PHPStan rules (used in their high-scale system) to:

• Block anti-patterns (e.g., array casts, arithmetic on strings) early.
• Enforce modern PHP (e.g., readonly, match for enums) without manual audits.
• Customize rules per project (e.g., disable enforceReadonlyPublicProperty for legacy code). Example: The forbidCheckedExceptionInCallable rule alone would’ve caught X production bugs in our last release by flagging unhandled exceptions in closures. Zero false positives—just stricter defaults we control.*

Ask: "Which of these rules align with our top technical debts? We can start with a pilot module."