Phpstan Rules Laravel Package

Product Decisions This Supports

• Enforcing strict coding standards: Adopting this package aligns with initiatives to enforce stricter type safety, immutability, and best practices in PHP development. This supports a roadmap item to improve code quality and reduce runtime errors by leveraging static analysis.
• Build vs. Buy: This is a clear "buy" decision—it provides pre-validated, production-proven rules that would take significant effort to implement in-house. The package fills gaps in PHPStan’s native strictness, reducing the need for custom rule development.
• Use Cases:
  • New projects: Ideal for teams starting fresh with Laravel/PHP, where strictness from day one prevents technical debt.
  • Legacy codebases: Gradually introduce rules to incrementally improve code quality without breaking existing functionality.
  • Team onboarding: Standardize coding practices across developers, reducing inconsistencies and bugs.
  • Security/compliance: Rules like forbidCheckedExceptionInCallable and forbidArithmeticOperationOnNonNumber mitigate risks by catching edge cases early.
  • Performance: Rules like enforceIteratorToArrayPreserveKeys prevent subtle bugs that could impact performance (e.g., unintended key loss in arrays).

When to Consider This Package

• Adopt if:
  • Your team prioritizes type safety, immutability, or exhaustive validation (e.g., enums, generics).
  • You’re using PHP 8.1+ (for features like readonly, match expressions, and generics).
  • You want to reduce runtime errors by catching issues at static analysis time.
  • Your codebase is medium-to-large (small projects may not need this granularity).
  • You’re already using PHPStan and want to extend its strictness without reinventing the wheel.
• Look elsewhere if:
  • Your team lacks static analysis maturity (e.g., no existing PHPStan setup).
  • You’re constrained by legacy PHP versions (e.g., <8.0) or frameworks that conflict with strict rules (e.g., older Laravel versions with dynamic properties).
  • You need highly custom rules—this package is opinionated; disable/enable rules as needed.
  • Your project has performance-sensitive code where strict rules might introduce false positives (e.g., forbidCast could break legacy array-to-object conversions).
  • You prefer minimal tooling—this adds complexity to your CI/CD pipeline.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us enforce industry-leading PHP code quality with minimal effort. By adopting ShipMonk’s strict PHPStan rules, we’ll catch critical bugs early—like unsafe type comparisons, unhandled exceptions in callbacks, or mutable public properties—reducing production incidents. It’s a low-cost, high-impact way to align our codebase with best practices, similar to how teams at ShipMonk (a logistics tech company) use it. The rules are configurable, so we can tailor them to our needs without sacrificing safety. This supports our goals of scalability and developer productivity by reducing technical debt."

For Engineering Leaders:

*"This package extends PHPStan’s strictness with 40+ rules that ShipMonk uses in production. Key benefits:

• Type Safety: Blocks risky comparisons (e.g., objects, enums) and enforces native type hints.
• Immutability: Mandates readonly for public properties, reducing side effects.
• Exception Safety: Catches unchecked exceptions in callables/generators, which PHPStan misses.
• Consistency: Standardizes naming (e.g., *Test suffix for tests) and array handling. It’s zero-maintenance—just install and configure. We can phase in rules gradually (e.g., start with enforceNativeReturnTypehint and forbidCast), and the documentation shows exactly how to disable anything opinionated. This aligns with our quality-first culture and reduces fire drills from subtle bugs."

For Developers:

*"Think of this as PHPStan on steroids. It catches edge cases native PHPStan misses, like:

• Comparing objects/enums with >/< (which works in PHP but is error-prone).
• Forgetting preserve_keys in iterator_to_array (a common source of data loss).
• Using mutable public properties (anti-pattern in modern PHP). You can opt out of any rule, and the config is straightforward. It’ll save you time by flagging issues before they hit QA. Example: If you accidentally write if ($enum === Case1) elseif ($enum === Case2), it’ll nudge you to use match ($enum) instead—future-proofing your code against new enum cases."