Coding Standards Laravel Package

Technical Evaluation

Architecture fit

• This is a dev-time tooling package, not an application library: it ships a PHP_CodeSniffer ruleset (plus custom sniffs) consumed via phpcs. Runtime footprint is zero, so it cannot affect Laravel request lifecycle, container bindings, or deploy artifacts.
• The ruleset is built for Human Made's WordPress agency work (WordPress-Extra/Docs lineage, HM-specific naming and docblock conventions). Laravel idioms — facades, fluent query builders, Blade-adjacent PHP, PSR-4 app namespaces under App\ — are largely out of scope for its intent, and several sniffs will produce noise rather than value.
• Fit is therefore peripheral, not architectural: it belongs (if at all) in the same layer as Pint, PHPStan, and PHP-CS-Fixer — a CI quality gate — rather than in the framework stack.

Integration feasibility

• Mechanically trivial: composer require --dev humanmade/coding-standards, add a phpcs.xml.dist referencing the vendor ruleset, wire vendor/bin/phpcs into Composer scripts and CI. No service, migration, or config surface in the app itself.
• Realistic effort is 1–3 engineer-days for a spike: install, run against an existing Laravel codebase, and triage the violation report. The triage — not the install — is the cost.
• Feasible as a selective ruleset (cherry-picking individual sniffs or excluding WordPress-specific categories) rather than an all-in adoption.

Technical risk

• Low blast radius, medium adoption risk. No production exposure; the downside is wasted engineering time and developer friction if the ruleset fights Laravel conventions.
• Toolchain overlap: Pint (PHP-CS-Fixer) and phpcs are separate engines but overlapping mandates. Running both without a clear division of responsibility produces formatter churn in diffs and conflicting auto-fix expectations.
• Dependency drift: PHP_CodeSniffer major-version transitions historically break rulesets. A single-vendor, agency-maintained project (161 stars) may lag on PHPCS 4 / PHP 8.4+ support.
• Governance unknown: verify license compatibility, security disclosure process, and release cadence before mandating it org-wide.

Key questions

1. Do we own any WordPress or WordPress-adjacent PHP that would make this ruleset a net positive?
2. Which specific sniffs justify adoption that slevomat/coding-standard + PSR-12 + PHPStan do not already cover?
3. Who owns the exclusions file, and what is the process for adding/removing rules?
4. Is the license and support model acceptable for a mandated CI gate?
5. Does it support our minimum and maximum PHP versions?

Integration Approach

Stack fit

• Composer-native, PSR-4 autoloaded, installed under require-dev — consistent with how a Laravel team already consumes Pint, PHPStan, and Rector. No conflict with Laravel's service provider or config caching model.
• Best-fit scenario: a monorepo containing both Laravel services and WordPress plugins/themes, where one linting standard across PHP code has organizational value.
• Poor-fit scenario: a pure Laravel codebase, where PSR-12 + Laravel Pint + PHPStan level 6+ covers ~95% of the value with better framework alignment.

Migration path

• Phase 0 (spike, 1–2 days): run the full ruleset in report-only mode against one representative Laravel repo; capture violation counts by sniff category.
• Phase 1: if signal is real, promote to a curated ruleset — inherit only the sniffs that pass the triage, exclude WordPress-specific categories explicitly with documented rationale.
• Phase 2: wire as a non-blocking CI job (continue-on-error: true), then ratchet to blocking for changed files only (phpcs-changed or a diff-scoped runner) to avoid a mass reformat commit.
• Phase 3: only if Phase 2 stabilizes, apply the curated standard to the WordPress-side repos where it is genuinely native.

Compatibility

• Verify the package's PHP and PHPCS constraints against the team's matrix; pin the PHPCS version in composer.json if the ruleset is version-sensitive.
• Confirm coexistence with Pint: define Pint as the auto-formatter (write path) and phpcs as the gate (read path), or exclude overlapping sniff categories. Do not run both in fix mode.
• Check CI image availability for any required extensions and ensure lint runs are cached/parallelized to keep PR feedback under a few minutes.

Sequencing

1. License/security/version-matrix review (blocks everything).
2. Report-only spike against one repo.
3. Sniff-by-sniff triage and curated ruleset authoring.
4. Non-blocking CI on changed files.
5. Blocking gate + developer docs; only then expand scope.

Operational Impact

Maintenance

• Ongoing cost is ruleset curation and version-bump babysitting, not code changes. Budget roughly a few hours per quarter plus reactive work on PHPCS major releases.
• Pin versions in composer.lock; treat ruleset upgrades as reviewed PRs that may generate large diff noise.
• Because the package is small and single-maintainer, plan for the possibility of forking the ruleset into an internal company/coding-standards package — low effort, and it removes upstream cadence as a dependency.

Support

• No commercial support; upstream is community/agency-driven. Internal ownership must be explicit (typically the platform or developer-experience team).
• Documentation burden is real: developers need a clear "which tool fixes what" guide, or they will disable rules ad hoc.

Scaling

• Linearly cheap: lint time grows with LOC; mitigate with parallel PHPCS, changed-file-only runs, and CI caching.
• Adding repos is low-friction once the curated ruleset exists — that is the actual scaling lever, not the package itself.
• Organizational scaling risk is standards fragmentation: three overlapping PHP style tools across N repos is harder to govern than one.

Failure modes

• Noise cascade: full ruleset on Laravel code flags hundreds of non-issues, team disables the gate, tool is abandoned — most likely outcome and the primary reason to reject all-in adoption.
• Formatter conflict: Pint and phpcs auto-fix fight each other, producing unstable diffs.
• Upstream stall: package lags PHPCS support, blocking PHP upgrades until forked or removed.
• Silent rot: gate stays green because the ruleset was over-excluded to unblock a release.
• Supply-chain: dev dependency only, so production risk is negligible; still apply standard dependency review.

Ramp-up

• Minimal for anyone who has used PHP_CodeSniffer: under a day. Non-trivial for the curator who must understand each sniff's intent to justify exclusions — that is the real onboarding cost.
• Recommend a short internal note with four things: how to run locally, how to read the report, the exclusion policy, and the escalation path for disputed rules.

TPM recommendation

• Verdict: evaluate-only, low strategic priority (consistent with the 17.2 opportunity score). Do not mandate for Laravel repos. Fund a 1–2 day spike only if the organization has WordPress PHP in scope or a specific sniff gap that Slevomat + PHPStan cannot close. Otherwise, standardize on Pint + PHPStan and revisit annually.