Tighten Coding Standard Laravel Package

Technical Evaluation

Architecture fit. Treat tightenco/tighten-coding-standard as a policy artifact, not a platform dependency. It is a dev-only PHP_CodeSniffer ruleset that composes PSR-12, Laravel-flavored conventions, and Tighten-specific sniffs. It ships in no production artifact, has no runtime surface, and is removable with a composer remove plus a deleted phpcs.xml. What it actually encodes is a decision about what "correct" PHP looks like in our repos. The package delivers no capability on its own — value is realized only through uniform CI enforcement — so the TPM question is not "does it install" but "can we get every PHP service onto one pinned version and keep it there." That makes this a governance rollout with a named owner and a decision record, not a library evaluation.

Integration feasibility. Mechanically cheap; organizationally it needs coordination across three fronts. First, PHPCS external standards require installed_paths registration, which in practice means allow-listing dealerdirect/phpcodesniffer-composer-installer in the Composer 2.2+ plugin config — a change to the shared CI base image that needs platform-team ownership and a security review of a plugin with autoload/filesystem access. Second, most Laravel shops already run Laravel Pint (PHP-CS-Fixer based), so running both produces overlapping opinions, duplicate findings, and conflicting auto-fixes. Third, editor tooling must be distributed to match CI or developers will see a different standard locally than the pipeline enforces. The Pint-versus-PHPCS decision must precede install, because reversing it later means re-normalizing the whole tree.

Technical risk. Log these as risk-register entries with owners and detectable signals:

• Silent non-enforcement (highest severity). If the standard fails to register, PHPCS either errors or runs an empty ruleset; teams have shipped "green" pipelines that enforced nothing. A gate that manufactures false assurance is worse than no gate. Mitigation: a committed fixture with known violations that CI must reject.
• Version coupling. Sniffs track PHP tokenizer behavior; new language features (enums, readonly, attributes, first-class callables) historically produce false positives until upstream catches up, and PHPCS 4.x is a breaking release for standards authors. Mitigation: pin the PHPCS minor, gate upgrades behind the smoke test.
• Sole-consumer support model. Zero stars, zero dependents, v1.0.2 as the visible ceiling — assume we are the only consumer. No community triage validates behavior on our PHP matrix, and upstream will not prioritize our edge cases. Treat it as vendor-authored sample configuration, not a supported product.
• Opinion drift. The ruleset encodes one consultancy's house style (docblock-heavy, agency-style Laravel) that will diverge from evolving PSR-12/PER-CS over time. Adoption is a commitment to a third party's editorial taste.
• Accidental production inclusion. Cheap to prevent (require-dev, --no-dev in release builds) but worth an explicit build assertion.

Key questions before funding.

1. Who is the named owner, and what fraction of an FTE is committed to phpcs.xml, the baseline, and suppression policy?
2. Which PHPCS major does it pin, and does that survive composer update across our PHP support matrix?
3. What is the true install footprint — does it bundle PHPCompatibility or assume it?
4. Is Pint or PHPCS the formatter-of-record, and who signs that ADR?
5. What is phpcbf's auto-fix coverage, and are the fixers safe (no semantic rewrites, no docblock destruction)?
6. Is upstream active or ossified — and does that change fork-vs-pin?
7. Do we treat this as a style aid or as audit evidence? If the latter, stop: there is no vendor SLA to point at.

Integration Approach

Stack fit. Good fit: Composer-based PHP/Laravel services already running PHPCS, or legacy code where baselined, changed-files-only enforcement is acceptable. Poor fit: Pint-first organizations with no appetite for a second formatter; greenfield projects where PHPCS plus slevomat configured directly gives cleaner ownership; and any org with an existing published standard, where layering creates conflicting rules and erodes trust in the gate. The strongest fit is a new or small Laravel codebase where the team already follows Tighten's published guidance and the opinions feel native rather than imposed.

Migration path. Stage it so no single PR carries both behavioral change and mass reformatting.

• Phase 0 — Decision record. Formatter-of-record (Pint vs PHPCS), fork-vs-pin strategy, named owner. Exit: signed ADR. This is the hard gate.
• Phase 1 — Report-only pilot. One or two new services, dev dependency installed, phpcs.xml committed, non-blocking CI job with --report=summary. Exit: violation count (our debt estimate), CI wall-clock delta measured, developer sentiment captured.
• Phase 2 — Institutionalize. Vendor/fork and pin the ruleset into the repo, register it in the shared CI image, distribute editor config repo-wide, add the known-bad fixture. Exit: the deliberate-violation test fails CI as expected.
• Phase 3 — Enforce narrowly. Blocking gate on changed files only, or a PHPCS baseline freezing existing violations. Exit: four consecutive weeks with no false-positive-driven bypasses.
• Phase 4 — Paydown or sweep. Shrink the baseline directory by directory; reserve a whole-tree phpcbf commit for a quiet branch window as its own no-functional-change PR.
• Phase 5 — Go/no-go on org-wide mandate, reviewed against agreed metrics at roughly one quarter.

Compatibility. Confirm three things before Phase 1 closes: the CI PHP image version against sniff constraints; the plugin allow-list entry present in every pipeline that runs PHP, not just the pilot's; and editor plugin parity with phpcs.xml — mismatched local/CI standards is the single most common cause of "it passed on my machine."

Sequencing and dependencies. ADR → shared CI image → editor config distributed → enforcement → mass fix. Order matters: ship editor config before the blocking gate or PRs become style ping-pong, and keep the mass auto-fix last and isolated because it is the only irreversible artifact in the program. Pair PHPCS with Pint (or PHP-CS-Fixer) so style fixes are automatic and the sniffer only flags what needs human judgment.

Rollback. Trivial up to Phase 3 — revert the composer.json/phpcs.xml commit and drop the CI step. After a full-tree phpcbf sweep, rollback means a revert PR with conflict cost, which is exactly why the sweep is isolated and late.

Operational Impact

Maintenance. Low continuous engineering cost, but non-zero and ownerless by default. The real budget line is configuration ownership: someone must own the ruleset, the baseline file, the ignore-comment policy, and the upgrade cadence, or the standard decays into a wall of inline suppressions nobody reviews. Pin the PHPCS minor, read the changelog on every bump, and schedule for a breaking event at PHPCS 4. Revisit on each PHP major upgrade.

Support. The weakest dimension. Zero dependents means no community triage, no knowledge base, and no expectation that an issue about our PHP version gets fixed. Define internal support explicitly: the fork is our code, upstream is reference material. Budget a few hours per PHP minor upgrade to validate against the fixture, and document deltas from upstream so a future maintainer can rebase rather than reverse-engineer.

Scaling. Scales well technically — PHPCS is fast, deterministic, and parallelizable — but the policy does not scale by default. Every new repo, language version, and editor multiplies drift surface. Standardize through a shared CI image and a scaffolded phpcs.xml template so new services inherit the gate rather than re-deciding it. Track: style-related review comment volume, PR cycle time, CI duration delta, suppression-comment count, and percentage of files compliant.

Failure modes. (1) False green — ruleset not registered; pipeline passes while enforcing nothing. Detect with the committed known-bad fixture; this is the one control that must never be dropped. (2) False-positive fatigue — new PHP syntax trips a stale sniff, engineers start adding blanket ignores, and the gate loses credibility. Detect by suppression-comment growth. (3) Toolchain conflict — Pint and PHPCS disagree, CI and pre-commit hook disagree, developers learn to ignore both. Prevented by the Phase 0 ADR. (4) Silent decay — no owner, no upgrades, standard drifts from the language; detect by fixture runs on the newest PHP image. (5) Blame pollution — a mass format commit obscures history; contain by isolating the sweep.

Ramp-up. Expect roughly hours, not sprints, to a report-only pilot, and one engineering day to a documented, tested, pinned baseline in a shared CI image. Developer ramp-up is a single editor-plugin install plus a README pointer, but only if the editor config is distributed before enforcement — otherwise onboarding time-to-first-merged-PR regresses instead of improving. New engineers benefit most: an enforced, published standard gives objective, non-personal feedback on their first PRs. Budget a named maintainer at a small but explicit fraction of an FTE; that commitment, not the install, is what determines whether this package is still enforcing anything six months from now.