Phpcsextra Laravel Package

Product Decisions This Supports

• Engineering standards roadmap — build vs. buy. Adopting a maintained sniff collection replaces the recurring cost of hand-writing and maintaining custom PHPCS rules. Write-your-own is only justified for org-specific conventions (naming, layering, framework idioms) that this package deliberately doesn't cover; treat PHPCSExtra as the baseline layer and reserve custom sniffs for the delta.
• PHP modernization program. The Modernize ruleset directly supports a migration initiative (e.g., a PHP 8.x upgrade or "modern PHP" push): it auto-fixes dirname(__FILE__) → __DIR__, collapses nested dirname() calls, and — when a php_version is configured — only flags changes valid for the target version. This turns a modernization epic into a measurable, incremental, CI-enforced workstream rather than a one-off refactor.
• Code review throughput. Auto-fixable formatting and consistency sniffs (NormalizedArrays, attribute bracket/parentheses spacing, modifier keyword order, trailing commas) remove stylistic nitpicks from PR review, shifting reviewer attention to design and correctness. Track this as a leading indicator: violations per PR, review comments per PR, and time-to-merge before/after adoption.
• Consistency across a multi-repo / multi-team portfolio. A shared, versioned ruleset (pinned in composer.json) is the cheapest mechanism for making dozens of Laravel/PHP services look and behave the same, and it's enforceable and auditable in a way that a written style guide is not.
• Defect prevention at the cheap end of the pipeline. DuplicateArrayKey, MixedArrayKeyTypes, MixedKeyedUnkeyedArray, ForeachUniqueAssignment, NoEchoSprintf, and ConstructorDestructorReturn catch real bug classes pre-merge. Each is a candidate to enable behind a violation-count baseline, so you can sequence rollout by ROI instead of adopting everything at once.
• Prioritizing tech-debt work. --report=info metrics per sniff give you a quantified inventory of modernization and consistency debt per repository — useful input when sequencing cleanup work against feature work, and a defensible "we reduced X violations by Y%" narrative for quarterly reviews.
• Guardrails for AI-assisted and third-party code. As generated and contributed code volume rises, an automated, deterministic style/modernization gate becomes a product-quality control rather than a developer preference.

When to Consider This Package

Consider it when:

• The team already runs PHP_CodeSniffer (directly or via an existing custom/company ruleset) and wants additional, modern sniffs without writing them.
• You're planning or executing a PHP version upgrade and want enforcement to land incrementally, respecting a configured php_version.
• You need array formatting normalization or duplicate/mixed-key detection specifically — these are the strongest, least-subjective wins here.
• You want a cheap supplement to an existing standard (PSR-12, a company standard) rather than a full replacement; the package is explicitly a collection, not an opinionated end-to-end standard.
• You can afford the real cost of adoption: a short curation exercise to pick sniffs, set properties, and wire it into CI and pre-commit hooks.

Look elsewhere / proceed with caution when:

• You're all-in on Laravel Pint or PHP-CS-Fixer. Pint is a different engine and won't consume PHPCS rulesets. Adopting this means running a second linting stack in parallel — a real maintenance and developer-experience tax. Decide deliberately, not by drift.
• You need a single, ready-to-use standard. Universal is explicitly not a standard and contains contradictory sniffs by design. Using it wholesale will produce conflicting findings; it must be cherry-picked sniff-by-sniff, which is curation work someone must own.
• You expect vendor support or SLAs. Small community project (~100 stars, negligible downstream dependents, maintained under the PHPCSStandards org). It's well-engineered — changelog, releases, docs, broad PHP 5.4–8.5 test matrix — but bus-factor and support expectations should be set explicitly.
• You need risky fixers applied automatically. Universal.Classes.RequireFinalClass is flagged as a risky fixer with potential runtime side effects; it must never run unattended on application code. Similarly, ForeachUniqueAssignment's fixer preserves existing (possibly unintended) behavior. Gate these behind human review.
• Licensing policy is restrictive. LGPL-3.0 is fine for a dev-only, unmodified Composer dependency in virtually all organizations, but it's not MIT/Apache — confirm against your legal policy, especially if you'd ever fork and redistribute.
• Toolchain is pinned to old PHPCS. Requires PHP_CodeSniffer 3.13.6 / 4.x and PHPCSUtils 1.2.3+; verify this doesn't force major upgrades elsewhere in the CI image.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a free, LGPL-licensed developer tool that plugs into our existing code-quality checks and automatically enforces modern PHP practices and consistent code formatting. It carries zero production risk — it's a dev-only Composer dependency, never shipped in the application — and its blast radius is limited to CI and developer machines. The value is straightforward: less reviewer time spent on style, fewer mechanical defects reaching QA, and a measurable dashboard for our PHP modernization effort. Cost is a few days of one engineer's time to curate the rule set and wire it into CI; ongoing cost is a version bump.

For engineering leadership:

• Composability over commitment. It ships three rulesets — Modernize, NormalizedArrays, and Universal — that layer onto the standards we already run. We adopt incrementally, sniff by sniff, and can back any of it out with a one-line composer.json change.
• Version-aware. Configure php_version once and the sniffs only flag changes valid for our target runtime, so adoption is compatible with a phased upgrade rather than blocked on it.
• Mostly auto-fixable. The majority of sniffs ship with phpcbf fixers, so remediation cost is largely automated — with a documented exception list for risky fixers we will review manually.
• Operational shape. Install as a require-dev dependency via Composer; pin the version; add a phpcs step to CI and a phpcbf step to pre-commit; publish a short ruleset-rationale doc so developers know why each sniff is on.
• Honest caveats. It is a library of sniffs, not a turnkey standard — Universal must be cherry-picked and contains mutually exclusive rules. RequireFinalClass is a risky fixer. The project is community-maintained with a small downstream base, so we own the curation and pinning discipline; forking is a fallback, not a plan. And if we intend to standardize on Laravel Pint, we should have a deliberate conversation about running two linting engines rather than letting both creep in.

Ask: Approve a time-boxed pilot — one engineer, two sprints — to curate a ruleset on the two highest-churn repositories, with success measured by (1) reduction in style-related review comments, (2) a documented violation baseline that trends down, and (3) no CI regressions.