Coding Standard Laravel Package

Technical Evaluation

Architecture fit: Still a development-time tooling package with zero application runtime coupling, but 1.0.0 changes what is being adopted. It is now a three-tool toolchain with an explicit division of roles: PHP-CS-Fixer as the primary formatter (PER-CS 3.0, shipped as a config factory Config::create(__DIR__)), PHP_CodeSniffer 4 as a supplementary structural/semantic layer, and Rector as a new transformation step. That is a materially larger architectural commitment than the 0.x "rulesets plus config" package. The package also now imposes a platform constraint — PHP ^8.4 — which makes it a driver of the organization's runtime upgrade roadmap rather than a passive consumer of it.

Integration feasibility: Feasibility drops from "high on paper" to "conditional." Three gates now sit in front of adoption:

• PHP 8.4 is mandatory. Any repo on 8.3 or earlier must be upgraded first, which turns a lint rollout into a platform migration. This must be sequenced, not assumed.
• PHP_CodeSniffer ^4.0 is required. PHPCS 4 is a new major; other sniffs/rulesets, IDE integrations, and CI plugins in the estate may not yet support it. Coexistence with existing PHPCS tooling needs verification per repo.
• Pint overlap is now resolved by design. Because PHP-CS-Fixer is promoted to primary and ships its own config, the open question from the 0.x assessment ("reconcile with Pint or replace it") effectively answers itself: this package is a Pint replacement, not an additive layer. That simplifies the decision but raises the change-management cost.

The 0.x → 1.0 upgrade is a documented, mechanical but large diff (run composer cs, review and commit). Documentation improved — custom sniffs are now documented in one place (including the previously undocumented Functions.MissingOptionalArgument) and there is a copyable auto-fix CI workflow — which materially reduces the support and reverse-engineering burden flagged previously.

Technical risk: Runtime blast radius remains low; change risk is now moderate-to-high for a tooling package:

• Breaking requirements: PHP 8.4 and PHPCS 4.0 are hard breaks for existing adopters.
• Risky rules on by default: @PHP8x4Migration:risky and @PHPUnit10x0Migration:risky are enabled, so upgrades can produce behavior-adjacent rewrites, not just whitespace.
• Test-suite churn: php_unit_method_casing enforces snake_case test method names with the PSR1 CamelCaps sniff excluded for tests/. This will rename tests at scale and can break naming-based test selection, CI filters, or reporting dashboards. It is cosmetic in code but disruptive in tooling that keys off method names.
• A new tool with semantic reach: Rector is added to the toolchain (composer rector). The release explicitly delegates assertEquals → assertSame to AssertEqualsToSameRector because it only rewrites provably-scalar assertions — a good decision, and evidence the maintainers are thinking about false-positive rewrites. But it also confirms Rector can make semantic edits, so it must be scoped and reviewed, not lumped into "style."
• Validation is still thin. The release does not change the adoption picture: this remains a low-external-adoption vendor standard, so the organization still owns the upgrade path. The active maintenance signal is positive (two PRs, a maintainer, a documented 1.0) but not a substitute for internal ownership.
• Governance surface widened: the new single auto-fix workflow runs Rector, PHP-CS-Fixer, and phpcbf, then commits fixes back via stefanzweifel/git-auto-commit-action v7. That introduces a bot that writes to branches — a policy, branch-protection, and review question that did not exist in the prior assessment.

Key questions:

• Which repos are already on PHP 8.4, and what is the cost/owner for the remainder? Can adoption proceed only on the 8.4-ready subset?
• Is PHPCS 4.0 compatible with all other sniffs, IDE plugins, and CI integrations currently in use?
• Does the organization standardize on PHP-CS-Fixer (replacing Pint) or attempt to keep both? If Pint is removed, what is the deprecation path for existing pint.json configs?
• Are the @PHP8x4Migration:risky and @PHPUnit10x0Migration:risky presets individually toggleable, so teams can stage risky rules behind formatting rules?
• What is Rector's scope in this standard — style-adjacent modernization only, or a general upgrade tool? Who reviews its diffs?
• What is the policy for the auto-commit workflow: allowed on PR branches only, never on protected branches? Does it require a CODEOWNERS review?
• Is there a supported exception/ignore mechanism for snake_case test naming and for ordered_class_elements member ordering?
• Who owns upstream maintenance, and has the project committed to a release cadence post-1.0 (semver, deprecation policy)?
• Does the toolchain support changed-file scanning, parallel execution, and CI caching across all three tools?

Integration Approach

Stack fit: Good fit for Laravel repos on Composer and modern CI (GitHub Actions, GitLab CI), conditional on PHP 8.4. Install as require-dev; production images stay untouched. The critical framing for stakeholders: this is not a lint config, it is a standardized toolchain plus a style source of truth. Pint should be treated as superseded where this package is adopted, and pint.json files should be retired deliberately rather than left to drift.

Migration path: Two tracks, run in parallel.

• Platform track: inventory PHP versions, upgrade target repos to 8.4 (or confirm they are already there), and verify PHPCS 4 compatibility before any style work begins.
• Standard track: pilot in one 8.4-ready repo. Replace the PHP-CS-Fixer config with Config::create(__DIR__), keep <rule ref="IxDFCodingStandard"/> in phpcs.xml, and delete formatting sniff overrides that no longer exist. Run composer cs in dry-run to size the diff.

The 1.0 diff is large and mechanical. Land it as isolated commits split by category — formatting (PHP-CS-Fixer), test method renames, Rector transformations — so reviewers can skim mechanical changes and scrutinize semantic ones. Add .git-blame-ignore-revs so attribution survives. Do not let Rector rewrites share a commit with formatting.

Compatibility: Pin PHP-CS-Fixer, PHP_CodeSniffer 4, Rector, and the package version together, and validate against the organization's supported PHP/Laravel matrix — the matrix and the toolchain are now coupled at the 8.4 boundary. Confirm PHPCS 4 does not conflict with any remaining first-party sniffs. Verify CI runtime for all three tools before making the gate blocking; measure full-repo vs changed-file.

Sequencing:

1. Confirm PHP 8.4 readiness and PHPCS 4 compatibility in the target repo set.
2. Decide and document the Pint replacement (kill pint.json, one source of truth).
3. Pilot one repo: replace configs, run dry-run, size the diff.
4. Land the mechanical upgrade in segregated commits; enable .git-blame-ignore-revs.
5. Run the auto-fix workflow on PR branches only; decide whether bot commits require review.
6. Enable blocking checks on new/changed code (not full-repo) and define the exception policy.
7. Expand repo-by-repo with pinned versions; add pre-commit hooks and developer docs.

Operational Impact

Maintenance: Higher than 0.x, and the profile changed. The organization now maintains three tool versions (PHP-CS-Fixer, PHPCS 4, Rector) plus the standard itself. Rector is the biggest new maintenance burden: it has a fast release cadence and its rules change behavior, so each bump deserves a dry-run and a diff review, not a blind patch bump. Assign an owner for pinning, upstream review, and rule-change announcements. Adoption remains low, so retain the fork/vendor contingency — 1.0 is a healthy signal, not a guarantee of upstream longevity.

Support: Two distinct audiences. Engineers fluent in PHP-CS-Fixer/PHPCS ramp fast; teams that only knew Pint need guidance on the new split of responsibilities ("PHPCS alone is no longer a complete standard — run composer cs"). The now-documented custom sniffs, the consolidated docs, and the copyable CI workflow meaningfully lower support load. Expect a spike in questions during the first upgrade, driven mostly by the snake_case test rename and the risky-preset fixes. Internal docs should cover install, the three commands, auto-fix usage, the Rector review policy, and the exception process.

Scaling: Config sharing still scales well across repos, and the single consolidated workflow replaces the previous two style workflows — a net simplification in CI surface. The cost shifts to execution time: three tools across the repo is more expensive than one, and Rector is the slowest. Use changed-file scanning, parallel execution, and caching; avoid full-repo blocking runs on large legacy codebases until baselines exist. The auto-commit action is a scaling risk at high PR volume — many bot commits across many repos will consume CI minutes and reviewer attention, so scope it tightly.

Failure modes:

• PHP 8.4 gate blocks adoption for a large part of the estate, stalling the rollout mid-program.
• PHPCS 4 ecosystem gaps break unrelated sniffs, IDE integrations, or CI plugins.
• Large mechanical diff gets bundled with functional changes, producing unreviewable PRs and a loss of blame attribution.
• Snake_case test renames break naming-based CI filters, test selection, or reporting.
• Risky presets by default introduce fixes teams did not opt into, including test assertions.
• Rector over-reach — semantic rewrites slipping in under a "style" label.
• Auto-commit bot vs. branch protection — commits that bypass required reviews or trigger loops.
• Line-length loosening (180 warn / 220 error) lets previously-blocked long lines pass, which some teams may read as a regression in strictness.
• Strategic: adopting a low-adoption vendor standard without an internal owner. Mitigate with pinned versions, a pilot, Rector review gates, and a documented fallback to an internal fork.

Ramp-up: Longer than the prior estimate. Budget two to four sprints per team once PHP 8.4 is in place, front-loaded by the size of the mechanical diff and the test rename — plus a separate, org-wide platform track for the 8.4 upgrade. Treat these as distinct line items in planning. TPM success metrics: PHP 8.4 readiness across target repos, CI duration delta per repo, volume and size of the one-time auto-fix PRs, style-related review comments post-adoption, exception count (especially for test naming and member ordering), bot-commit review rate, and repository adoption rate against the 8.4-ready denominator.