Php Cs Fixer Custom Fixers Laravel Package

Technical Evaluation

Architecture fit

This package is developer tooling, not application architecture. It registers additional rules into PHP CS Fixer and therefore has zero runtime footprint in a Laravel application — no service provider, no config publishing, no autoload cost in production (require-dev only). It slots into the existing code-quality tier alongside Pint, PHPStan/Larastan, and Rector. The correct framing for prioritisation is "DX / consistency improvement," not "platform capability," so it should be evaluated and funded out of the tooling backlog rather than competing with feature work.

The real value is concentrated in a subset of fixers (e.g. NoCommentedOutCodeFixer, CommentedOutFunctionFixer, ClassConstantUsageFixer, NoUselessCommentFixer, NoSuperfluousConcatenationFixer, NoUselessParenthesisFixer) rather than the full catalogue of ~50. Roughly seven fixers are already marked deprecated in favour of native PHP CS Fixer rules (DataProviderNameFixer, DataProviderReturnTypeFixer, DataProviderStaticFixer, InternalClassCasingFixer, MultilinePromotedPropertiesFixer, NumericLiteralSeparatorFixer, PhpDocPropertySorterFixer), which tells us the package is partly a staging ground that upstreams into PHP CS Fixer. That is a good signal for quality and a bad signal for long-term dependency surface.

Integration feasibility

Mechanically trivial: composer require --dev, then in .php-cs-fixer.dist.php call ->registerCustomFixers(new PhpCsFixerCustomFixers\Fixers()) and enable rules via Fixer::name(). Two Laravel-specific frictions matter:

1. Pint is the incumbent. Laravel teams standardise on Pint, and Pint's pint.json does not expose custom-fixer registration — rules can only reference PHP CS Fixer's built-in rule set. In practice this means either running a second, raw php-cs-fixer invocation in CI alongside Pint, or replacing Pint with a hand-rolled PHP CS Fixer config. This must be verified against the current Pint version before committing, because it drives the whole integration shape.
2. Shim caveat. When PHP CS Fixer is installed via php-cs-fixer/shim (common in PHAR-style CI images), the package's bootstrap.php must be required to autoload its classes. Miss this and CI fails with class-not-found errors that look like a broken install.

Technical risk

Low-to-moderate, and almost entirely confined to CI and code review:

• No production blast radius. Dev-only dependency; worst case is a red pipeline.
• Rule conflicts. PHP CS Fixer aborts on conflicting rules at config load. Several fixers here are opinionated against Laravel/PSR-12 norms — notably DeclareAfterOpeningTagFixer (same-line declare(strict_types=1)) and NoImportFromGlobalNamespaceFixer (bans use DateTime;), both of which collide with prevalent Laravel style and with native rules. These should be excluded up front, not discovered in a failed build.
• Risky fixers. A large block is explicitly flagged risky (NoNullableBooleanTypeFixer, IssetToArrayKeyExistsFixer, ForeachUseValueFixer, NoUselessStrlenFixer, NoReferenceInFunctionDefinitionFixer, PhpUnitAssertArgumentsOrderFixer, CommentedOutFunctionFixer). These can change semantics; they need a dry-run review gate, not silent enablement.
• Blade files. PHP CS Fixer's default finder matches *.php, which captures *.blade.php. Without an explicit exclusion the tool will attempt to reformat Blade templates. This is the single most likely way to cause real damage.
• Deprecation churn. Every major release may drop the deprecated names, breaking the config file. Pin the version and read the changelog on every bump.
• Supply chain / bus factor. Single-maintainer project, 244 stars, effectively no downstream dependents. Compensating signals are strong: MIT, changelog, releases, high test coverage, mutation and type-coverage badges. Risk is acceptable for a dev dependency but argues against deep coupling.

Key questions

• Does our current Pint version permit registering custom fixers, or do we accept a two-tool pipeline?
• Which of the deprecated fixers do we actually need, and what is the upstream replacement timeline before removal?
• What is the PHP × PHP CS Fixer × Pint version matrix we must support across our apps?
• Do we have legacy directories (storage/, bootstrap/cache/, _ide_helper.php, migrations, generated code) that need exclusion or baselining?
• Are our test suites Pest-based? If so, the PHPUnit data-provider fixers are largely inert and the value proposition shrinks.
• Who owns the shared coding-standard package, and what is the upgrade cadence and rollback path?
• Do reviewers have budget for a one-off formatting commit, or will this fragment history?

Integration Approach

Stack fit

Composer-based Laravel apps and monorepos; CI on GitHub Actions or GitLab CI. Ships as a require-dev entry, ideally not required directly by every app but transitively via an internal acme/coding-standard package that also declares Pint and PHPStan config. That keeps the version bump in one place and prevents 20 repos drifting onto different rule sets.

Migration path

1. Inventory (½ day). Run php-cs-fixer with the candidate subset in --dry-run --diff mode against the repo. Triage output into "safe, adopt," "risky, review," and "conflicts with our conventions, drop."
2. Curated subset (½ day). Start with ~8–12 non-risky fixers that Pint does not cover. Explicitly exclude DeclareAfterOpeningTagFixer, NoImportFromGlobalNamespaceFixer, and anything in the deprecated list whose native equivalent already exists.
3. Ratchet. Land one dedicated formatting commit, add it to .git-blame-ignore-revs, then enforce via CI with --dry-run --diff so new violations fail the build.
4. Consolidate. Over the following quarter, migrate deprecated rules to native PHP CS Fixer names and re-evaluate whether the package is still pulling its weight.

Compatibility

Verify the declared PHP and friendsofphp/php-cs-fixer constraints against our lowest-supported PHP version. Confirm no rule collisions at config load (PHP CS Fixer fails fast, which is helpful here). Confirm Pest vs PHPUnit split per repo — the fixer value proposition differs materially between them.

Sequencing

Define a single canonical formatter order and document it. If running both tools, the pragmatic order is raw php-cs-fixer with the custom subset first, then Pint as the final word on style — this avoids the two tools oscillating on the same constructs. Do not enable CommentedOutFunctionFixer and NoCommentedOutCodeFixer together without testing; the first comments code out, the second wants commented-out code gone. Validate that pairing in the pilot before it reaches CI. Run locally through a composer fix script so developers never memorise the invocation.

Operational Impact

Maintenance

Low but non-zero, and it belongs to a named owner. Pin an exact version, let Renovate/Dependabot raise bumps, and review the changelog for deprecations and removals on every upgrade — this package's majors are the most likely source of CI breakage. Budget roughly an hour per release cycle. The internal coding-standard package is what keeps this from multiplying across repos.

Support

Minimal internal support load. The README is generated from the fixer implementations and includes per-fixer before/after diffs, which is genuinely good self-service documentation for developers who hit an unfamiliar change. Escalation path for "the formatter did something weird" is the config file, which is version-controlled and reviewable.

Scaling

Centralise the config; that is the whole scaling story. For large repos or monorepos, use --parallel, the on-disk cache, explicit path scoping, and in PR pipelines --path-mode=intersection so only changed files are checked. Naive full-repo runs on a large Laravel monorepo will add minutes to CI and get disabled by developers within a sprint.

Failure modes

Ramp-up

One to two days end-to-end for the pilot including review. Developer learning curve is genuinely low because the fixers are self-documenting in diffs, but reviewers need one explicit instruction: formatting-only PRs are reviewed by scope, not line by line, and are landed in isolation. Skip pre-commit hooks initially — they slow the loop and generate bypass behaviour; CI enforcement is sufficient.

Recommendation. Proceed with a time-boxed pilot of a curated, mostly non-risky subset, with Pint retained as the canonical style authority. Treat this as a low-cost, low-risk DX improvement worth roughly a sprint-day of effort, not a strategic investment — and set a two-quarter checkpoint to decide whether native PHP CS Fixer rules have made the dependency redundant.