Phpcs Rules Laravel Package

Technical Evaluation

What this package is: pekral/phpcs-rules is a PHP_CodeSniffer standards ruleset (dev-tooling only). It does not ship runtime code, so integration risk is confined to developer machines and CI pipelines rather than production services.

Architecture fit: Good, with a caveat. A PHPCS ruleset is a low-coupling dependency — consumed as a require-dev package and referenced via phpcs.xml <rule ref="..."/>. It has no runtime surface, no service boundary, no data contracts. The only architectural coupling is the transitive constraint it places on the PHP version of the environments that run static analysis.

The material change in 0.5: composer.json now requires php: ^8.5. This is not a stylistic break — it makes the package uninstallable on PHP 8.4 and below. Composer will refuse to resolve, which means the upgrade is not "optional churn"; it is a hard gate on the toolchain PHP version, independent of what the application actually runs on.

Technical risk (ranked):

1. PHP 8.5 availability — highest risk, and unverified. PHP 8.5 is not GA at the time of writing (expected late 2025). If our CI images, developer machines, or base containers cannot run 8.5, 0.5.x is simply not adoptable today. This must be confirmed against our actual toolchain before any planning; the release notes assume an 8.5-capable environment exists.
2. Dual-version support burden. Once we adopt 0.5.x anywhere, we are in a split state: some repos/CI lanes on 0.4.x, some on 0.5.x. Rulesets that diverge across repos produce inconsistent lint results — the exact failure mode a shared standard exists to prevent.
3. Silent behaviour change in the ruleset (medium). Re-enabling SlevomatCodingStandard.Functions.StaticClosure and excluding Classes.ReadonlyClass changes lint output. Under semver this is correctly a minor, but for a lint ruleset a minor bump can turn green builds red. Consumers should expect new violations without a code change on their side.
4. Reduced CI coverage upstream (medium). Dropping the 8.4/8.5 matrix and running everything on a single 8.5 worker is an upstream cost decision, not ours to contest — but it means the maintainer no longer validates 8.4 at all. Any 0.4.x maintenance we depend on is now unexercised by their pipeline.
5. Supply-chain / maintenance concentration (low-medium). Single-maintainer-style project with ^8.5 pinning suggests opinionated release cadence. Not a blocker, but it argues for pinning exact versions rather than ranges.

Key questions to resolve before committing:

• Is PHP 8.5 GA and available in our CI image, devcontainer, and any Docker base images used for linting? What is the date?
• Does the maintainer intend to backport fixes to 0.4.x, and for how long?
• Do we actually need 0.5.x features, or are we upgrading purely for currency? (If the latter: defer.)
• How many new violations do the StaticClosure / ReadonlyClass ruleset changes produce against our codebase?
• Can we run PHPCS in an isolated container on 8.5 while applications stay on 8.4?
• Is this package on our dependency-update automation, and is it currently auto-merging minors?

Integration Approach

Stack fit: Compatible in shape — any Laravel/PHP repo already running PHPCS can consume it. What changed is the environment requirement, not the integration mechanism. Fit is therefore conditional on PHP 8.5 being runnable in the lint lane.

Recommended posture: defer adoption, pin deliberately.

• Pin current consumers to 0.4.* (exact-ish constraint, e.g. ~0.4.8) with a comment in composer.json recording the PHP 8.5 gate and the review date.
• Do not allow 0.5.x to arrive via automated minor-bump PRs. Add a constraint/exclusion in the dependency bot config.
• Treat 0.5.x as a tracked upgrade ticket with an explicit trigger condition (PHP 8.5 GA + CI image availability), not a routine bump.

Migration path (when the trigger fires):

1. Isolate the runtime. Stand up a PHPCS job that runs in a dedicated PHP 8.5 container image, decoupled from the application runtime image. Lint tooling does not need to match the app's PHP version — this is the single most important sequencing decision, and it lets us adopt the ruleset without forcing an application-wide PHP upgrade.
2. Prove the delta. On a branch, swap 0.4.x → 0.5.x and run the full ruleset against the codebase. Capture the violation diff attributable to StaticClosure and ReadonlyClass. Decide per-repo whether to fix, baseline, or exclude.
3. Land ruleset and fixes together. A dependency bump that turns CI red is worse than no bump; the composer.json change and the resulting code fixes must be one reviewable unit.
4. Roll out by repo criticality, not all at once — start with the lowest-traffic repo, then the shared phpcs.xml template, then the rest.
5. Retire 0.4.x only when every repo's lint lane is on 8.5 and the upstream 0.4.x line is confirmed EOL.

Compatibility notes:

• If any application must stay on PHP 8.4 (framework version, hosting constraint), it can — provided linting is containerised. If linting must run on the same image as the app, that repo is blocked on 0.5.x until it upgrades PHP.
• The ruleset changes will produce new findings. Budget remediation effort; estimate from the diff in step 2, not from the changelog.

Sequencing summary: verify 8.5 availability → decouple lint runtime → measure violation delta → adopt in one repo → template → fleet → drop 0.4.x. Nothing in that chain is urgent, and the cost of waiting is low. The cost of being early is a broken CI across every repo at once.

Operational Impact

Maintenance: Low ongoing effort, but with a new pinning obligation. Someone must own the "PHP 8.5 readiness" ticket and the review date, otherwise the package silently freezes at 0.4.8 while the rest of the toolchain moves. Add a calendar reminder / backlog item with an owner.

Support: Upstream support for 0.4.x is the open question. The changelog's own guidance ("Projects still on PHP 8.4 should stay on the 0.4.x line") implies the branch is expected to persist, but the removal of 8.4 from CI means it is no longer tested — support is nominal, not active. Plan on no upstream fixes for 8.4; if we hit a bug, we patch or exclude the sniff ourselves.

Scaling: Trivially scalable. A ruleset has no runtime footprint, no throughput characteristics, and no per-request cost. The only scaling dimension is repo count, and the lever there is the shared phpcs.xml template — centralise the rule set and version pin so N repos don't drift into N configurations.

Failure modes and mitigations:

Ramp-up: Minimal. No new concepts for anyone who already runs PHPCS — it's a constraint bump and one or two rule toggles. Expect ~half a day for a developer to run the delta and triage findings, plus remediation time proportional to the StaticClosure hit count. The genuinely new knowledge is operational, not technical: the team needs to understand why lint runs on a different PHP version than the app, or someone will "helpfully" align them and break the pipeline later.

Bottom line for the TPM: This is a small, contained, dev-tooling change that is currently not adoptable pending PHP 8.5 GA. The correct action today is to pin, exclude from automation, assign an owner, and schedule re-evaluation — not to migrate. The package remains a safe dependency at 0.4.8; the risk is entirely in an unmanaged or automated upgrade.