Php Cs Fixer Custom Fixers Laravel Package

Product Decisions This Supports

• Build vs. buy (buy, clearly): This is a dev-only Composer dependency (MIT, no runtime footprint, no service to operate). It extends PHP CS Fixer rather than replacing it, so the decision is "adopt a rule pack," not "adopt a platform." The cost of reversal is one composer remove and deleting config lines — which means it should be trialed rather than debated.
• Definition-of-done / quality-gate roadmap item: If your roadmap includes "reduce review cycle time" or "raise baseline code quality," this package is a cheap lever. It converts subjective style comments into an automated, non-negotiable CI check.
• Feature-level use cases that map to actual bug classes: several fixers are correctness-adjacent, not cosmetic — NoDuplicatedArrayKeyFixer (silent key collisions), NoUselessStrlenFixer, NoSuperfluousConcatenationFixer, NoDuplicatedImportsFixer, PhpUnitAssertArgumentsOrderFixer (inverted expected/actual assertions produce misleading failure output). These are defects a PM can point to in a retro.
• Legacy cleanup scoping: NoPhpStormGeneratedCommentFixer, NoDoctrineMigrationsGeneratedCommentFixer, NoUselessDoctrineRepositoryCommentFixer, NoCommentedOutCodeFixer give you a mechanical, reviewable diff for "clean up the old repo" work — useful for sizing a tech-debt sprint instead of estimating it by hand.
• Upstream-absorption signal (important): multiple fixers are marked DEPRECATED because PHP CS Fixer itself absorbed them (DataProvider*, InternalClassCasing, MultilinePromotedProperties, NumericLiteralSeparator). This tells you the package's value is a moving frontier, not a fixed asset — so decide up front whether you're committing to tracking its releases, and budget a small annual migration task. Do not enable deprecated fixers; they will break on upgrade.
• Onboarding investment: a shared fixer config is documentation that executes. It reduces the "how do we write PHP here?" question load for new hires.

When to Consider This Package

Adopt when:

• You already run PHP CS Fixer (friendsofphp/php-cs-fixer) in CI and are on a maintained 3.x line with PHP 8.x.
• Your team's style guide has outgrown @PSR12 / @Symfony / @PhpCsFixer presets and you're hand-enforcing rules in code review.
• You want stricter semantic rules (nullable booleans, isset vs array_key_exists, reference parameters), not just whitespace.
• You have legacy PHPUnit or Doctrine code where these fixers produce high-signal diffs.
• You're willing to run a two-tier rollout: non-risky fixers enforced immediately, "risky" fixers enabled file-by-file or directory-by-directory.

Look elsewhere / defer when:

• Your Laravel team has standardized on Laravel Pint. Pint is built on PHP CS Fixer but exposes a narrower config surface; confirm custom-fixer registration works for your Pint version before committing — if it doesn't, this package is a poor fit regardless of quality.
• You use ECS or rely solely on Rector for automated changes; running two overlapping style engines creates conflicting diffs and ownership confusion.
• You have no CI lint stage. Adding a fixer pack before adding the gate is backwards — build the gate first.
• You only want rules that are now upstream. Enable them natively and skip the dependency.
• Team size is very small (1–3 devs) and review friction is low; setup and upgrade overhead can exceed the benefit.
• You need Laravel-domain rules (blade, Eloquent conventions, migration formatting). This package is framework-agnostic; it won't help there.

Also flag: single-maintainer project (~244 stars, low dependent count). Bus factor is the primary risk. Acceptable here because the blast radius is a dev dependency you can fork or drop, but it argues for pinning the version and treating upgrades as scheduled work, not automatic.

How to Pitch It (Stakeholders)

To executives (30 seconds): A free, MIT-licensed add-on for our existing PHP linting tool. It's a development-only dependency — it never ships to production and cannot affect users. Setup is roughly half a day; the payoff is fewer manual style corrections in code review and a handful of real defect classes caught automatically (duplicate array keys, misleading test assertions, dead commented-out code). Fully reversible if it doesn't work out.

To engineering: Add kubawerlos/php-cs-fixer-custom-fixers as a require-dev dependency, register new PhpCsFixerCustomFixers\Fixers() in the existing .php-cs-fixer.php config, and enable fixers by name. Rollout:

1. Enable the non-risky, high-signal fixers first (NoDuplicatedArrayKeyFixer, NoDuplicatedImportsFixer, NoUselessParenthesisFixer, CommentSurroundedBySpacesFixer, NoTrailingCommaInSinglelineFixer).
2. Run in report-only mode for one sprint to size the diff before it blocks anyone.
3. Enable risky fixers (ForeachUseValueFixer, IssetToArrayKeyExistsFixer, NoNullableBooleanTypeFixer, NoReferenceInFunctionDefinitionFixer, CommentedOutFunctionFixer) per-directory, with a code owner reviewing the first pass — each has documented behavioral caveats.
4. If PHP CS Fixer is installed via the php-cs-fixer/shim package, add the bootstrap.php require to the config, or classes won't load.
5. Pin the version; exclude all DEPRECATED-marked fixers from config; schedule a quarterly check against upstream PHP CS Fixer so absorbed rules are migrated rather than left to break.

Success metrics: count of style-only review comments per PR (target: near zero), PR time-to-approval, and lint failures caught pre-merge vs. style nits caught in review. Re-evaluate after one quarter — if the fixer config isn't being extended or maintained, that's a signal the team didn't actually want the stricter baseline.