Coding Standards Laravel Package

Technical Evaluation

Package category: Dev-only static-analysis tooling. arxeiss/coding-standards is a PHP_CodeSniffer ruleset.xml distributed as a Composer package — it ships no runtime code, no service provider, no facades, and therefore carries zero production blast radius. For a TPM this is the most favorable risk class available: adoption is reversible with a single composer remove --dev and a CI config edit.

Architecture fit: Good conceptual fit for Laravel/PHP shops that want opinionated, centrally versioned style enforcement. It slots in as a require-dev dependency referenced by path from a project or org-level ruleset.xml. It does not replace Laravel Pint — Pint wraps PHP-CS-Fixer, not PHPCS — so teams already standardized on Pint would be running two overlapping fixers, which is a real source of conflicting auto-fixes and developer frustration. Architectural fit is therefore conditional: this package makes sense if the org's linting spine is PHP_CodeSniffer (often for its sniff-rule granularity, Slevomat sniffs, or legacy codebases already on PHPCS); it is a poor fit as a second opinion alongside Pint.

Integration feasibility: Technically trivial — one Composer line, one XML include, one CI step. The effort is not integration, it is normalization: applying a new ruleset to an existing codebase surfaces a violation backlog that must be either fixed, baselined, or scoped to changed files. Budget for that, not for the install.

Technical risk:

• Bus factor of one. Eight stars, zero dependents, a single maintainer. No downstream usage means no community regression coverage — you would be the first production consumer of each release.
• Version coupling. Custom rulesets pin PHPCS, PHP, and sniff-package versions (Slevomat, etc.) in their composer.json. Any drift between this ruleset's constraints and the host project's PHP/PHPCS version produces resolver conflicts that block unrelated dependency upgrades — a classic dev-dependency lock.
• Silent behavior change. A ruleset bump can add sniffs that fail previously-green CI with no code change on your side. Without pinning and a changelog review step, this is an unpredictable CI failure source.
• Low signal on quality. A 2.15 score with zero dependents and near-zero stars is not evidence of poor code; it is evidence of no evidence. Treat the package as unvetted and require a code read before adoption.
• Mitigant: Apache-2.0 permits forking and vendoring. The entire artifact is declarative XML — cheap to audit, cheap to own.

Key questions:

1. What PHPCS major version and PHP version range does the ruleset constrain, and does that conflict with our current PHP matrix?
2. Which sniff packages does it declare, and are those pinned to ranges we can live with?
3. Does it ship a canonical ruleset.xml designed for inclusion, or is it primarily a self-testing repo we would have to fork?
4. Does the ruleset support ignoring/baselining, and does it include any custom (non-upstream) sniffs we would have to maintain?
5. Is there a documented release/changelog discipline, and how often have rule additions been shipped as breaking changes?
6. Is Pint or PHP-CS-Fixer already the org standard, and if so, does this duplicate it?

Integration Approach

Stack fit: Fits any PHP 8.x codebase with Composer and a CI pipeline; fits Laravel projects specifically only where the team has chosen PHPCS as the enforcement layer. It composes cleanly with PHPStan/Psalm (complementary, no overlap), and composes poorly with Pint/PHP-CS-Fixer in fixer mode.

Migration path:

1. Fork-or-vendor decision first. Given zero dependents and a single maintainer, do not consume the upstream repo by path. Either mirror it into the org's internal Composer registry or fork into the org namespace and pin the fork. This converts an unmaintained external dependency into an owned, auditable asset — the entire cost is a ruleset XML we can read in an afternoon.
2. Wrap, don't consume directly. Create an internal org/coding-standards package whose ruleset.xml includes the upstream ruleset and layers org-specific overrides. Every project depends on the wrapper, never on the upstream directly. This gives one place to patch rules and one place to swap the upstream out.
3. Pin exactly. Use an exact version constraint plus a committed composer.lock. Treat ruleset upgrades as reviewed PRs with a CI dry-run attached.

Compatibility: Verify PHPCS major version alignment and the PHP version matrix before any code changes. If the org runs mixed PHP 8.1/8.3 images, confirm the ruleset's sniffs are version-neutral or split the ruleset per matrix entry.

Sequencing (advisory → enforcing):

• Phase 0 — Evaluate (1–2 days): Run phpcs --standard=<ruleset> --report=summary against two representative repos, one greenfield and one legacy. Quantify violation counts per sniff. This number determines whether the rollout is a sprint or a program.
• Phase 1 — Advisory CI (2 weeks): Add the check as a non-blocking job. Measure noise, identify the highest-volume sniffs, and decide which to disable via the wrapper.
• Phase 2 — New-code gate: Enforce on changed files only (diff-scoped linting) so legacy debt does not block delivery. This is where adoption succeeds or dies.
• Phase 3 — Baseline legacy: Introduce a PHPCS baseline file for untouched legacy code, then ratchet: fail if violation count increases.
• Phase 4 — Full enforcement: Only after the backlog is burned down or baselined, flip to blocking on the whole tree.

Operational Impact

Maintenance: Low ongoing effort, but non-zero ownership effort. Realistically the upstream package should be assumed frozen. Budget roughly a few hours per quarter to review upstream changes and merge them into the fork, plus one-time fork setup. Because the artifact is declarative XML, maintenance is a code review task, not an engineering task.

Support: No SLA, no vendor, no downstream community. Support model is internal: whoever owns the wrapper package owns the ruleset. Document that owner explicitly — otherwise the ruleset becomes an orphan that nobody dares change and everyone works around with // phpcs:ignore.

Scaling: Operationally cheap — PHPCS is CPU-local, adds seconds to CI, scales horizontally with existing build runners. The scaling constraint is social, not technical: as the number of repos grows, rule changes propagate to all of them simultaneously via the wrapper. This is the desired behavior but requires a change-management gate, otherwise a Tuesday afternoon wrapper bump red-lines forty pipelines at once.

Failure modes and mitigations:

• Upstream abandonware → fork and vendor; upstream becomes a reference, not a dependency.
• Ruleset bump breaks CI across all repos → pinned versions in the wrapper, upgrade only via a reviewed PR with an attached dry-run diff across a sample of repos.
• Dependency resolver conflicts with PHPCS/sniff packages → wrapper package declares and constrains these itself; the upstream never enters a project's dependency graph directly.
• Developer friction / mass phpcs:ignore → Phase-1 advisory period exists precisely to tune the ruleset before enforcement; if a rule generates ignore-comments at scale, delete the rule from the wrapper.
• Two fixers fighting (Pint + PHPCS) → pick one enforcement layer per repo; if Pint wins, this package is not adopted.

Ramp-up: Low. PHPCS is ubiquitous in PHP tooling; the incremental learning is "how to write and override a ruleset.xml," which is well-documented upstream and takes an engineer under a day. The real onboarding cost is communicating why a rule exists so the team does not treat lint output as noise. Include the wrapper's rationale in the repo README rather than pointing at an unfamiliar 8-star upstream.

TPM recommendation: Do not adopt as a live external dependency. Adopt as a forked-and-wrapped ruleset if and only if the org has standardized on PHP_CodeSniffer and accepts a single-owner maintenance model for the wrapper. If the org is on Pint, the correct decision is to skip this package and encode the same conventions as a Pint preset — the value here is the ruleset content, not the distribution vehicle, and the content is forkable under Apache-2.0.