Coding Standards Laravel Package

Technical Evaluation

Architecture fit vanio/coding-standards is a PHP_CodeSniffer ruleset, not a runtime library. It is a require-dev-only artifact that contributes an XML ruleset definition (likely ruleset.xml plus a handful of custom sniffs) consumed by phpcs/phpcbf. Architecturally it is a leaf dependency: it has no runtime coupling to a Laravel application, no service provider, no config publishing, and no database or queue surface. Fit with a Laravel codebase is therefore conditional on whether the team's style guide maps onto PHP_CodeSniffer at all — Laravel shops that have standardized on Pint or PHP-CS-Fixer (the Laravel default since 9.x) would be introducing a second, parallel formatting toolchain, which is the main architectural friction point. For teams already running PHPCS with PSR-12 or Slevomat, this drops in as an additional ruleset with near-zero blast radius.

Integration feasibility Mechanically trivial: composer require --dev vanio/coding-standards, reference it from the project phpcs.xml, and wire vendor/bin/phpcs into CI and a pre-commit hook. Real effort is not installation but rule adjudication — an opinionated external ruleset will surface a large first-pass violation count on an existing codebase, and every rule needs a decision (adopt, exclude, or override in phpcs.xml). Budget most of the effort for that triage and for the exclusions file, not the integration itself.

Technical risk The dominant risk is provenance, not code. Zero stars and zero dependents on a package published by a vendor (Vanio) strongly suggests an internal standard extracted for reuse rather than a maintained community project. That implies: no external users to surface regressions, no documented support window, and a real chance the repository is archived or left pinned to an older PHP_CodeSniffer major. Secondary risks are version coupling (PHPCS 3.x vs 4.x ruleset/sniff API changes; PHP 8.x tokenizer changes) and custom sniffs becoming false-positive generators on newer syntax (enums, readonly properties, first-class callables, property hooks in 8.4). Because it is dev-only, a break degrades CI rather than production — the blast radius is bounded, which makes this a tolerable risk if the code is vendored.

Key questions

• Is the repository actively maintained, and what PHP_CodeSniffer and PHP versions does the current release pin to?
• Does the ruleset depend on a specific parent standard (PSR-12, PSR-2, Slevomat) that we must also install?
• How much of the value is in custom sniffs versus a plain ruleset XML that we could reproduce in an afternoon?
• Is the license compatible with our distribution model, and is the ruleset stable enough to pin to a commit hash?
• Does it conflict with or duplicate Laravel Pint, and if so, which one owns formatting?
• What is the violation count if we run it against our codebase today?

Integration Approach

Stack fit Best fit is a Laravel monolith or a multi-package PHP estate that already runs PHP_CodeSniffer in CI and wants an opinionated, stricter-than-PSR-12 baseline. Poor fit where Pint is the established formatter and the team has no appetite for two style tools. Recommended posture: treat the package as a ruleset source, not a dependency of record — vendor a pinned copy or a fork into the repo (or an internal composer.json path repository) so CI cannot be broken by an upstream force-push, deletion, or unannounced ruleset change.

Migration path

1. Evaluate: install into a scratch branch, run phpcs --report=summary against app/, tests/, and database/, and quantify violations per sniff.
2. Curate: build a project phpcs.xml that includes the Vanio ruleset as a base and explicitly excludes or downgrades sniffs whose cost exceeds their value. Commit this file as the durable artifact — it is the thing that survives if the upstream package disappears.
3. Ratchet: adopt the standard in CI as non-blocking (continue-on-error or a warning-only report), then flip to blocking once the exclusion set is settled.
4. Scope: apply to new code first via a path-limited ruleset or a baseline file (--filter / baseline generation), keeping legacy directories excluded so the first blocking build is green.
5. Codify: add composer lint / composer lint:fix scripts and a pre-commit hook so developers get feedback before CI.

Compatibility Verify against the project's PHP version and the PHPCS version Composer resolves; PHPCS 4.x changed sniff interfaces materially, and a ruleset written for 3.x will not silently carry over. Check for a hard require on a PHPCS constraint that conflicts with the version Pint or another dev tool pulls in — dev dependency resolution conflicts are the most likely install-time failure. Confirm custom sniffs are autoloaded via the ruleset's <autoload> or the package's Composer autoload config.

Sequencing Do this as a contained, timeboxed spike behind a feature flag in CI, not as a cross-team initiative. Order: violation audit → ruleset curation → non-blocking CI → blocking on new code → optional blocking on legacy. Only after the curated phpcs.xml proves stable should anyone consider upstreaming fixes or forking; do not plan on upstream responsiveness.

Operational Impact

Maintenance Ongoing cost is low but non-zero and entirely internal: the curated phpcs.xml, the pinned commit or vendored copy, and periodic PHPCS/PHP version bumps. The recurring tax is rule drift — as the team adds exclusions the standard silently diverges from upstream, which is acceptable but should be acknowledged so nobody claims "we follow the Vanio standard" when they follow a local variant. Assume no upstream maintenance and plan the fork accordingly; ownership should sit with one named engineer, not a shared rotation.

Support No meaningful external support channel. Zero dependents means no Stack Overflow corpus, no issue history to mine, and no community to validate a workaround. Internal documentation of why each exclusion exists becomes the actual support artifact — without it, a future maintainer will re-litigate every rule from scratch.

Scaling PHPCS scales linearly with file count and is slow relative to PHP-CS-Fixer; on a large Laravel repo a full run can add minutes to CI. Mitigate with parallel execution (phpcs-parallel, or sharding by directory), running only on changed files in PRs, and reserving full runs for the main branch. The ruleset itself imposes no scaling concern — there is no runtime component — but CI wall-clock is a real cost at team size.

Failure modes

• Upstream deletion or archival breaking composer install — mitigated by vendoring/pinning.
• PHPCS major upgrade invalidating the ruleset or custom sniffs — surfaces as CI failure on a Composer update PR.
• False positives on new PHP syntax blocking legitimate merges — the highest-frequency day-to-day failure; mitigate with a fast path to add exclusions.
• Dev dependency resolution conflict with Pint or another tool pinning PHPCS.
• Divergence between local pre-commit hooks and CI if versions are not locked.
• Silent no-op: an incorrectly referenced ruleset results in PHPCS passing everything, giving false assurance — verify with a deliberately non-compliant fixture.

Ramp-up Installation is minutes; the real ramp is cultural. Expect one to two days of senior-engineer time for the initial violation audit and ruleset curation, plus a short team briefing on the new commands and on how to request a rule exclusion. Because there is no documentation to lean on, the curated ruleset and a brief README in the repo are the onboarding material. Overall verdict: low-effort, low-risk to pilot, but the value is entirely contingent on the ruleset genuinely reflecting the team's standards — if the answer to "what does this give us over PSR-12 plus Slevomat?" is not concrete, skip it and write a ruleset in-house.