Phpstan Rules Laravel Package

Product Decisions This Supports

• Build vs. buy for static analysis. The package is a curated set of PHPStan rules encoding Oro's application conventions. The decision it informs is whether to adopt Oro's guardrails wholesale versus authoring your own rule set — the former is faster to stand up, the latter is more precisely tuned to your codebase.
• Quality-gate roadmap. Adding a ruleset is a cheap, reversible increment on the CI pipeline. It gives you a concrete "definition of done" for code review and a measurable ratchet (baseline count of violations, trend over releases) that can be presented at roadmap reviews.
• Architectural drift control. Custom rules are the only durable mechanism for enforcing layering decisions — where business logic may live, which services may talk to which — once a team grows past the size where conventions survive on tribal knowledge. This package is a reference implementation of that pattern.
• Onboarding and review economics. Codified rules shift correction from senior-reviewer time to CI feedback. That is a headcount-adjacent decision: fewer review cycles per PR, faster ramp for new engineers, and a defensible answer to "why did this pattern slip in?"
• Use cases where it earns its place: teams on OroPlatform/OroCommerce, platform teams standardizing a large legacy PHP estate, and any org evaluating what a bespoke PHPStan extension looks like before committing engineering time to build one.

When to Consider This Package

Adopt when:

• You are building on or extending OroPlatform/OroCommerce, where these rules encode conventions your code is already expected to follow.
• PHPStan is already in CI at a meaningful level (level 5+) and the team has appetite for a stricter gate.
• You accept single-vendor stewardship: 13 stars, zero listed dependents, last release October 2024. Budget for pinning the version and being prepared to fork.

Look elsewhere when:

• You are not on Oro. The rules target Oro-specific abstractions and will produce noise, not signal, on a generic Laravel or Symfony codebase.
• You want broad PHP hygiene. Use phpstan/phpstan-strict-rules, framework extensions, and a coding-standard package instead — those are maintained by larger communities with faster release cadence.
• You need guaranteed long-term support or a vendor SLA. The MIT license helps, but the maintenance risk is real and should be a stated assumption in any adoption decision.
• The team has not yet stabilized PHPStan at a baseline level. Stacking custom rules on an unbaselined codebase converts a quality tool into a blocker.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed add-on to our existing static analysis tooling. It automates enforcement of architectural conventions that today consume senior engineer review time, and it gives us a measurable quality metric release over release. Cost is near zero; the risk is maintenance, which we mitigate by pinning the version and treating it as replaceable. Recommendation is a time-boxed pilot on one team, with a go/no-go based on violation signal quality.

To engineering: It is a set of PHPStan rules extracted from Oro's own products. Value is in the encoded conventions and as a template for writing our own rules — not in the rules themselves unless we are on Oro. Low adoption and a single maintainer mean we pin it, vendor it if needed, and do not treat it as a load-bearing dependency. The real win is proving the pattern: once we have one custom rule in CI, we can codify our own architectural decisions the same way.

Framing to avoid: presenting this as a security or correctness tool. It is a consistency tool. Its ROI is review time and onboarding speed, and it should be measured that way.