Phpstan Rules Laravel Package

Technical Evaluation

Architecture fit. oro/phpstan-rules is a static-analysis extension, not a runtime library. It ships additional rule classes that plug into PHPStan's rule registry and are wired in through a phpstan.neon include. Architecturally this is a leaf dev-dependency: it has no production surface area, no service provider, no runtime coupling to the application container, and no data-path implications. For any Laravel/PHP codebase already running PHPStan (level 5+), it is a purely additive quality gate. The rules are authored against Oro's own coding conventions (OroPlatform/OroCommerce), so the fit is strongest where the codebase's conventions overlap with Oro's — strict typing, explicit array shapes, annotation discipline — and weakest where Laravel's dynamic idioms (facades, magic properties, Eloquent's fluent builder) are the norm.

Integration feasibility. Straightforward. composer require --dev oro/phpstan-rules, then add the package's rules.neon to the includes block of the project's phpstan.neon. The main compatibility constraint is the transitive pin on phpstan/phpstan — the package targets a specific PHPStan major/minor line, and Larastan/other extensions in the same project must agree on that version. This is the most likely source of install friction. Because it is dev-only, a failed integration never reaches production.

Technical risk. Low-to-moderate, and asymmetric in the right direction. Blast radius is confined to CI. The realistic risks are: (1) a large first-run violation count against existing code, which stalls adoption unless baselined; (2) rules encoding Oro-specific opinions that conflict with a Laravel codebase's style, producing noise engineers will want to suppress; (3) version drift — the package has a single release in the last cycle and 13 stars, so PHPStan major upgrades may leave it behind temporarily; (4) single-vendor stewardship with effectively zero external dependents, meaning no community pressure to fix incompatibilities.

Key questions.

• Which PHPStan version(s) does the current release constrain, and does that match our Larastan/extension set?
• What is the measured violation count against our codebase at our current PHPStan level — is it a day of baselining or a quarter of remediation?
• Do the rules duplicate anything already enforced by Pint, PHP-CS-Fixer, or Larastan, and if so which wins?
• Is the Oro-specific rule set separable — can we cherry-pick individual rules rather than taking the whole bundle?
• What is our exit plan if the package goes unmaintained — can we vendor or fork the rule classes?

Integration Approach

Stack fit. Best suited to a Laravel codebase that has already standardized on PHPStan with a committed baseline and treats static analysis as a merge gate. Poor fit for teams still at PHPStan level 0–4, or teams without a CI pipeline that fails on analysis errors — the rules add value only if something acts on them. It is a complement to, not a replacement for, Larastan; expect some overlap in the type-inference domain and plan to resolve which extension owns which error.

Migration path. Treat this as an incremental ratchet, not a big-bang adoption:

1. Install as a dev dependency in a branch; resolve the PHPStan version constraint against the existing extension set first.
2. Run the full ruleset in report-only mode and capture the violation inventory, segmented by rule class.
3. Generate a PHPStan baseline for pre-existing violations so the gate is green from day one.
4. Enable failure-on-error in CI for new and modified code only.
5. Triage the baseline quarterly — either remediate or permanently exclude rule classes that conflict with house style.

Compatibility. Two axes to validate before committing: PHPStan version alignment across all installed extensions, and PHP runtime version support (the package's composer.json constraints gate this). Both are checkable in a throwaway branch in under an hour. Confirm the rules behave correctly under the project's autoload configuration and any custom PHPStan bootstrap files.

Sequencing. Do this after the PHPStan baseline itself is stable and after Pint/PHP-CS-Fixer formatting is settled — formatting churn and static-analysis churn in the same window makes attribution impossible during review. If the team is mid-migration to a newer Laravel or PHP major, defer: the PHPStan extension ecosystem lags framework upgrades, and adding a low-maintenance third-party ruleset during that window compounds debugging cost.

Operational Impact

Maintenance. Minimal ongoing effort in steady state — the package changes infrequently (one release in the trailing period) and requires no runtime upkeep. The real maintenance burden is the baseline file: it must be regenerated whenever the codebase shifts meaningfully, and it silently masks regressions if left untouched. Assign ownership of the baseline to a named engineer or the platform team; an unowned baseline rots into a permanent suppression list. Budget a small recurring cost for PHPStan major-version upgrades, where this package is the likely laggard.

Support. Single-vendor, open-source, MIT-licensed, with no commercial support tier. GitHub issues are the only channel and the issue volume is low because the dependent count is effectively zero — meaning a bug you file may sit without a response. Mitigation: the rule classes are small and readable; the team should be prepared to fork or vendor-patch rather than wait. This is acceptable for a dev-only tool and unacceptable only if it were a production dependency, which it is not.

Scaling. Scales well across repositories — the same includes stanza can be templated into a shared CI configuration, giving consistent analysis across a monorepo or a portfolio of services. The scaling cost is CI wall-clock time: additional rule passes lengthen the analysis job, and on a large codebase this can be material. Measure the delta before rollout; if it pushes the pipeline past its budget, scope the ruleset rather than accept slower feedback loops. Also account for per-developer experience — engineers running PHPStan locally (in an IDE or pre-push hook) get the same latency tax.

Failure modes.

• Constraint deadlock: package pins a PHPStan version incompatible with Larastan or another extension — install fails, work stops at step one.
• Baseline inversion: a bloated baseline suppresses genuine new errors; the gate looks green while quality degrades.
• Style conflict: Oro-flavored rules flag idiomatic Laravel code, engineers suppress broadly, and suppression becomes the default response to all static analysis.
• Abandonment: package stops tracking PHPStan releases, forcing an exit (fork, vendor, or removal) at a moment not of your choosing.
• Redundant enforcement: overlap with Pint/Larastan creates conflicting guidance and review friction.

Ramp-up. Low for the platform engineer wiring it in (an afternoon). Higher for the broader team: engineers need to internalize what the new rule classes are asking for, and the first few weeks will generate review-comment churn as people learn which patterns are now flagged. Pair the rollout with a short internal writeup mapping each rule class to the pattern it enforces — this is the difference between a gate engineers understand and a gate they route around. Given the 13-star, zero-dependent profile, frame the adoption internally as "evaluated and contained" rather than "strategic dependency," and keep the fork-and-vendor escape hatch documented before it is needed.