Php Cs Fixer Config Laravel Package

Getting Started

1. Install alongside the fixer, pinned. The package is a ruleset, not a fixer. Pull both in, and pin PHP-CS-Fixer to the major the package was built against (2019-era = 2.x):

   composer require --dev arubacao/php-cs-fixer-config friendsofphp/php-cs-fixer:^2.16
   

2. Create the config file at the repo root. On PHP-CS-Fixer 2.x this is .php_cs / .php_cs.dist; on 3.x it is .php-cs-fixer.php. The file just needs to return a PhpCsFixer\Config — the package hands you one preloaded with rules:

   <?php
   // .php_cs.dist
   $finder = PhpCsFixer\Finder::create()
       ->in(__DIR__)
       ->exclude(['bootstrap/cache', 'storage', 'vendor']);
   
   return Arubacao\PhpCsFixerConfig\Config::create()
       ->setFinder($finder);
   

   Confirm the exact namespace and factory (create() vs new Config()) against the README for your tagged release — the config object is standard PhpCsFixer\Config either way, so setRules, setFinder, setRiskyAllowed all compose normally.

3. Look at the package src/ before trusting it. The whole value is the rule array. Open the Config class and skim the keys — that is the actual standard you are adopting, and it is what you will fork if the archived package drifts from your needs.

4. First run — dry, on a narrow path. Do not fix the whole repo on day one:

   vendor/bin/php-cs-fixer fix --dry-run --diff --verbose --path-mode=intersection src/
   

5. Wire up Composer scripts so the team has one entry point and the fixer resolves from the lockfile, not a global install:

   "scripts": {
     "cs": "php-cs-fixer fix",
     "cs:check": "php-cs-fixer fix --dry-run --diff --using-cache=no"
   }
   

First use case: a fresh Laravel app where you want PSR-12-ish formatting plus Laravel idioms without hand-curating 100 rules. Run cs:check against a single domain directory, eyeball the diff, then widen.

Implementation Patterns

• Choose the preset to match the codebase. The package targets both Laravel and plain PHP. Apps get the Laravel preset (helper/facade import ordering, Blade-adjacent PHP); libraries and packages get the plain/PSR preset. Mixing them is the fastest way to churn a library's public signatures.

• Override by merging the resolved rules, not by guessing the preset. Get the base array out first, then layer:

  $config = Arubacao\PhpCsFixerConfig\Config::create()->setFinder($finder);
  $config->setRules(array_merge($config->getRules(), [
      'strict_comparison' => true,
      'ordered_imports'   => ['sort_algorithm' => 'alpha'],
  ]));
  return $config;
  

  Adding rules is safe. Removing a base rule is where silent regressions hide — leave a one-line comment explaining why each removal exists.

• Scope per directory. One root config for app/, config/, routes/, tests/; a second, stricter config for src/ in a monorepo. Run them as separate Composer scripts rather than one mega-finder.

• CI: make composer cs:check a required job. Use --dry-run --diff --using-cache=no; a cache restored from a previous run will happily report "no changes" after you edit rules.

• Pre-commit: fix only staged files so hooks stay fast:

  vendor/bin/php-cs-fixer fix --path-mode=intersection \
    $(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')
  

• Editor parity: point PHPStorm's file watcher / VSCode format-on-save at the same vendor/bin/php-cs-fixer and the same config file. If the editor falls back to its own PSR formatter, local and CI output will diverge and every PR picks up phantom changes.

• Baseline adoption: the first fix is a style-only commit touching hundreds of files. Isolate it, add the SHA to .git-blame-ignore-revs, then turn on the CI gate. Never mix it with a feature branch.

• Complement, don't replace, static analysis. PHP-CS-Fixer is formatting only — keep PHPStan/Psalm in a separate job.

Gotchas and Tips

• Archived since 2019. Treat it as a frozen rule snapshot, not a maintained standard. If you need to evolve it, copy the rule array into a local PhpCsFixer\Config subclass checked into your repo and drop the dependency — that makes the archived package an implementation detail instead of the source of truth.
• Version coupling is the main failure mode. The package predates PHP-CS-Fixer 3.x. On v3 you will hit renamed/removed rule sets (@PSR2 → @PSR12, deprecated individual rules). Symptoms: "unknown rule" exceptions, or the config silently loading fewer rules than expected. Either pin ^2.16 or diff the package's rule array against current v3 rules and maintain the override yourself.
• Config filename tracks the major version. .php_cs is not discovered by PHP-CS-Fixer 3.x — it looks for .php-cs-fixer.php. Half of "it works on my machine" reports are this.
• Cache lies. Default cache file is .php_cs.cache (v2) / .php-cs-fixer.cache (v3). After editing rules, delete it or run with --using-cache=no, otherwise stale results mask new violations.
• @ sets and individual rules interact non-obviously. A custom key only overrides the set entry with the exact same key; you cannot "remove" a rule a set implies except by replacing the whole set. Always inspect getRules() after construction rather than reasoning about it.
• Risky rules are off by default. Enabling any requires setRiskyAllowed(true) and can change runtime behavior (strict comparisons, declare(strict_types=1)). Keep them to a small, reviewed allowlist.
• Diff noise blows past review tooling. GitHub caps large diffs and reviewers stop reading. Schedule the initial sweep for a quiet window and exclude generated code up front: bootstrap/cache, storage/framework, vendor, public/build, and historical migrations you never intend to touch.
• Editor and CI drift usually traces to three things: different PHP-CS-Fixer versions, different PHP versions (rule behavior can vary), and different config discovery. Always invoke via vendor/bin/php-cs-fixer and print --version in CI logs.
• Natural successor: Laravel Pint ships an actively maintained PHP-CS-Fixer preset. If you are on Laravel ≥9, evaluate Pint before adopting this package. Rules are not identical, so migrating later produces a second large diff — budget for it now or migrate immediately.