Php Cs Fixer Laravel Package

Product Decisions This Supports

• Build vs. buy on code-style enforcement. This is a solved problem with a 13.5k-star, MIT-licensed, actively released tool. The decision this informs is "do we stop spending engineering time on hand-formatting and review nitpicks?" — the answer is yes, and the buy side is free. Nothing here should ever be a roadmap item to build in-house.
• Whether to adopt Laravel Pint or raw PHP CS Fixer. Pint is Laravel's first-party wrapper around this package. This assessment lets you decide deliberately: Pint for a single opinionated Laravel app (lower config surface, Laravel-default rules), raw PHP CS Fixer when you need multi-framework rule sets, custom fixers, @autoPHPMigration, or the same config across non-Laravel PHP services in the same org.
• PHP version upgrade roadmap and timing. The @autoPHPMigration and @autoPHPMigration:risky rule sets mechanically modernise syntax toward newer PHP. That directly shortens the critical path on "we must be off EOL PHP for security/compliance reasons" — a decision that otherwise costs weeks of senior-engineer time and blocks framework upgrades. Support spans PHP 7.4–8.5, so one tool covers the whole migration window.
• Delivery-quality investment level. Choosing to gate CI on php-cs-fixer check is a decision about where quality budget goes: it converts an unbounded, subjective review cost into a fixed, automatable one. It also makes "is this PR reviewable?" a machine answer rather than a reviewer-mood answer.
• Team scaling and onboarding design. A committed .php-cs-fixer.dist.php is executable documentation of house style. It reduces time-to-first-merged-PR for new hires and removes the "which reviewer do I copy?" problem — relevant if you're deciding whether to grow the team or the contractor pool.
• Repo topology / standardisation. If you're deciding between monorepo and many small services, or absorbing an acquisition's codebase, a single shared ruleset is a cheap normalisation lever that doesn't require rewriting business logic.
• Explicitly not a customer-facing feature. Do not put this on a product roadmap as user value. It belongs in platform/DX investment and should be justified by engineering throughput metrics (review cycle time, style-comment volume per PR, PHP-upgrade lead time), not by conversion or retention.
• Out of scope — do not let it drift into these decisions. It is not static analysis (that's PHPStan/Psalm), not a test generator, not a business-logic refactoring tool. Risky rule sets change code semantics; treating them as "just formatting" is how you get a production incident.

When to Consider This Package

Adopt when most of these hold:

• You run PHP 7.4–8.5 (Laravel 9–12 era) and have a CI pipeline you control — GitHub Actions, GitLab CI, or a Docker-based build.
• More than a handful of engineers touch PHP, or you have multiple PHP repos/services with visibly different style.
• Style is currently enforced by convention, review comments, or nothing — i.e. cost is real but unmeasured.
• You have a PHP upgrade on the horizon: the @autoPHPMigration path is the single strongest technical argument for this specific tool over generic linters.
• You want editor-level consistency (native PhpStorm support, VS Code/Vim/NetBeans plugins) so violations are caught before commit.
• You need a check/fix duality: check in CI as a hard gate, fix locally and in pre-commit hooks.

Look elsewhere, or defer, when:

• You're a solo developer or a script-sized codebase. The config, CI wiring, and version-pinning overhead exceed the value.
• You're already on Laravel Pint and satisfied. Pint wraps this package; adopting both creates two configs fighting each other. Prefer Pint and revisit only when you need rule sets Pint doesn't expose.
• Reformatting would create a massive unreviewable diff on a live legacy codebase. Sequence it: introduce check as non-blocking, format directory-by-directory in dedicated PRs with tests green, then flip to blocking. Do not do a single whole-repo fix commit.
• Your actual pain is bugs or type errors, not style. Route that budget to PHPStan/Psalm first — different tool, different problem, and confusing the two produces disappointing results.
• You need linting for non-PHP assets, or you need sniff parity with an existing PHP_CodeSniffer ruleset your team already maintains — migration cost may not pay back.
• You depend on PHP versions the tool doesn't yet support. There's an --allow-unsupported-php-version=yes escape hatch, but at your own risk — do not build a release gate on an unsupported target.
• Composer dependency conflicts bite. The php-cs-fixer/shim package exists specifically for this; try it before concluding the tool is incompatible.

Adoption cautions to plan for: pin the version in composer.json (release cadence is high — many patch releases with fixer-behaviour changes), treat risky rule sets as code changes requiring full test-suite sign-off, and never let the fixer run as a post-deploy or runtime step. It is a dev dependency, nothing more.

How to Pitch It (Stakeholders)

For executives (one paragraph): Engineering spends recurring, invisible time on code formatting and review nitpicks, and our PHP version upgrade is gated on manual code modernisation. PHP CS Fixer is a free, MIT-licensed, 13.5k-star, actively maintained developer tool that fixes both automatically. It's already the engine inside Laravel Pint, so it's the sanctioned path in our ecosystem rather than a novel dependency. Expected returns are shorter review cycles, smaller and more predictable PRs, faster onboarding, and a measurably shorter PHP upgrade — for roughly a day of setup plus CI minutes. There is no licensing cost, no runtime risk, and no customer-facing surface; it is a platform investment, not a product feature. The ask is engineering time, not budget.

For engineering leads (the technical case): Install as a dev dependency (composer require --dev friendsofphp/php-cs-fixer), scaffold with php-cs-fixer init, commit a .php-cs-fixer.dist.php, and wire php-cs-fixer check as a blocking CI step with php-cs-fixer fix locally and in pre-commit hooks. Start from @PER-CS or @auto — do not hand-roll a rule list. Layer @autoPHPMigration (and :risky where tests are trustworthy) as a separate, isolated PR with a green suite before merge. Pin the version, because patch releases do change fixer output. Keep the boundary clear: this fixes style and syntax modernisation; PHPStan/Psalm finds bugs. Two tools, two jobs, two CI steps.

For the wider org (the narrative): We are choosing to make code style a property of the build rather than a property of reviewer attention. That is a small, reversible, one-day decision with a well-maintained upstream, and it removes a recurring source of friction from every PR.