Coding Standard Laravel Package

Technical Evaluation

What this package is: A shared PHP coding-standard definition (typically PHP_CodeSniffer rulesets and/or PHP-CS-Fixer/Pint rule sets, possibly with Rector and PHPStan config) distributed as a Composer package for PHP and Symfony projects. It is a development-time tooling dependency only — no runtime footprint, no autoloaded production code, no service-provider registration expected.

Architecture fit:

• Fits cleanly as a require-dev Composer dependency; zero impact on production artifact size or bootstrap.
• Enforces a single style/quality contract across services and libraries — valuable in a polyrepo or multi-team PHP estate.
• Aligns with the standard Laravel delivery model (Composer + CI scripts), but is explicitly scoped to "PHP and Symfony," not Laravel, so framework-specific conventions (Blade, Eloquent, Laravel-prescribed idioms) are not guaranteed to be covered.

Integration feasibility:

• Low technical effort: composer require --dev, publish/point to the ruleset, wire a composer cs-check script into CI.
• Primary friction is distribution, not the tooling: the package lives on a self-hosted GitLab (git.var-lab.com), so every consuming repo and CI runner needs a repositories entry plus credentials (Composer auth token / SSH deploy key). This is a one-time but non-trivial setup and an ongoing secret-rotation obligation.
• If the package pins or shadows PHP-CS-Fixer/PHP_CodeSniffer versions, it can conflict with Laravel Pint (which bundles its own PHP-CS-Fixer constraint). Coexistence needs verification before rollout.

Technical risk:

• Maturity signal is weak: 0 stars, 0 dependents, score 0. Stars are meaningless on an internal GitLab, but zero dependents is meaningful — it suggests the package has not yet been adopted anywhere, so we would be the first real consumer and would absorb the early-adopter defects.
• Single point of failure: an internal GitLab outage or a force-push/tag deletion blocks composer install in every consuming pipeline unless artifacts are mirrored (Satis, Composer proxy, or a Packagist-style internal registry).
• Governance risk: unclear ownership, release cadence, semver discipline, and PHP-version support matrix. A coding standard that lags new PHP releases becomes a blocker on framework upgrades.
• Noise risk: rule changes land as repo-wide diffs, generating large, hard-to-review PRs and merge conflicts against in-flight work.
• Security surface: dev dependencies are still installed in CI with repository credentials; needs the same supply-chain scrutiny as production deps.

Key questions:

1. Which engines does it wrap — PHP_CodeSniffer, PHP-CS-Fixer, Pint, Rector, PHPStan, or a combination — and at which pinned versions?
2. What PHP versions and Symfony versions are supported, and what is the stated policy for adding new PHP releases?
3. Does it conflict with, replace, or complement Laravel Pint? Is Laravel explicitly in scope or explicitly out?
4. Who owns the package, what is the release/versioning policy, and what is the SLA for a fix when a rule breaks CI?
5. How is it distributed (VCS, Satis, private Packagist) and is there an offline/mirrored fallback?
6. Is the ruleset published as a versioned, immutable artifact, or do consumers track a branch?
7. What is the license and is it cleared for use across all teams?

Integration Approach

Stack fit:

• Laravel monolith or service: add as require-dev, expose composer cs / composer cs:fix scripts, run in the existing CI lint stage. No application code changes required.
• Libraries and shared packages: highest value here — a common standard prevents style churn when code moves between packages.
• Pint overlap must be resolved first. Laravel ships Pint by default; running both is redundant and version-conflict-prone. Decide: replace Pint with this standard, or run this standard only on non-Laravel packages.

Migration path:

1. Spike (1–2 days): install in a scratch branch of one low-risk repo, run the checker in report-only mode, and measure violation volume and rule overlap with Pint.
2. Baseline: adopt without reformatting — either grandfather existing violations via a baseline file or restrict enforcement to changed lines/files.
3. Pilot: one repo, one team, CI advisory (non-blocking) for two sprints.
4. Enforce: flip to blocking on the pilot repo; fix forward only.
5. Fan out: roll to remaining repos in waves, largest/most active last to limit merge-conflict pain.

Compatibility:

• Verify PHP constraint against our fleet's minimum and maximum supported versions.
• Verify no constraint collision with Pint, PHPStan, Rector, or PHPUnit already in composer.lock.
• Confirm the ruleset is consumable as a file reference (e.g., phpcs.xml <rule ref="...">) rather than requiring a custom binary.
• Confirm behaviour on PHP 8.3/8.4 deprecations — coding standards frequently lag and emit spurious warnings.

Sequencing:

• Dependency/distribution setup (Composer repo + CI credentials) → spike → Pint coexistence decision → pilot advisory → pilot blocking → staged rollout → governance handoff (owner, upgrade cadence, changelog review).

Operational Impact

Maintenance:

• Low ongoing cost if the package is actively maintained; otherwise it becomes a pinned, unowned dependency that blocks PHP/framework upgrades.
• Budget a small recurring effort for version bumps and for reviewing ruleset diffs before they land repo-wide.
• Require a changelog and semver discipline as a condition of adoption; a coding standard that ships breaking rule changes in patch releases is operationally hostile.

Support:

• Failures surface as CI failures, which developers escalate to platform/DevEx rather than to the package owner — be explicit about the routing.
• Needs a short internal runbook: how to install, how to suppress a rule with justification, how to request a rule change, how to get a hotfix.
• Provide IDE wiring (PhpStorm PHP_CodeSniffer inspection, VS Code extension) so developers get feedback before pushing.

Scaling:

• CI cost scales linearly with repo count and PHP file volume; enforce changed-files-only or cached runs on large repos.
• Parallelize (PHPCS --parallel) and cache the Composer/tool layer to keep lint stages under a couple of minutes.
• Registry/mirror must scale to every pipeline fetching the package; a VCS-mode dependency clones the whole repo per build — prefer a Composer proxy.

Failure modes:

• Registry/GitLab outage → all pipelines fail at install. Mitigation: mirror artifacts or vendor the ruleset into a base CI image.
• Credential expiry/rotation → silent install failures across the estate.
• Rule change lands repo-wide → mass reformat diffs, merge conflicts, blame noise, obscured real changes in review.
• PHP version lag → adoption becomes the blocker on a framework upgrade; teams rip it out under pressure, fragmenting standards.
• Pint/CS-Fixer constraint conflict → unresolvable composer update.
• Abandonment → the package ossifies at an old PHP version and is bypassed.
• False-positive fatigue → developers add blanket ignores, eroding the standard's value.

Ramp-up:

• Developer-facing: ~30 minutes (install, IDE config, suppression policy). Effectively zero for anyone already using Pint or PHPCS.
• Platform-facing: ~1–2 days for registry/auth setup, CI template changes, and the pilot.
• Org-facing: one short written standard-of-record plus an announcement; expect one to two sprints of friction during the blocking transition.
• Overall recommendation: worth piloting as a standardisation lever, but gate wider rollout on (a) confirmed ownership and release cadence, (b) a resolved Pint coexistence decision, and (c) a mirrored distribution path that removes the GitLab availability dependency. The zero-dependent signal means we should validate maturity on one repo before treating it as an estate-wide contract.