Php Cs Fixer Laravel Package

Getting Started

This is an opinionated ruleset wrapper around friendsofphp/php-cs-fixer, not a fixer itself. Treat it as a shared "house style" you drop into every Chief Tools–adjacent Laravel project.

1. Install as a dev dependency (never in require):

   composer require --dev chieftools/php-cs-fixer
   

   It will pull in friendsofphp/php-cs-fixer transitively; check composer.lock and don't separately require the fixer unless the package leaves it unconstrained.

2. Look at the package source first. With 0 stars and 0 dependents this is effectively an internal package, so the authoritative docs are src/ and the README. Identify:

   • the config factory (typically a class like ChiefTools\PhpCsFixer\Config with a make() / create() static method),
   • the rules array it returns,
   • whether it sets setRiskyAllowed(true),
   • the PHP version constraint it assumes.

3. Create .php-cs-fixer.dist.php at the project root and hand it a Finder scoped to your Laravel source dirs:

   <?php
   
   $finder = PhpCsFixer\Finder::create()
       ->in([
           __DIR__.'/app',
           __DIR__.'/config',
           __DIR__.'/database',
           __DIR__.'/routes',
           __DIR__.'/tests',
       ])
       ->exclude(['bootstrap/cache', 'storage']);
   
   return ChiefTools\PhpCsFixer\Config::make()
       ->setFinder($finder);
   

   Confirm the exact factory name against the package README — it's a small surface, but there's no stable public API guarantee here.

4. First use case: a dry run on a fresh/legacy Laravel app to see the blast radius before you commit to the style:

   vendor/bin/php-cs-fixer fix --dry-run --diff
   

   Then run for real, commit the diff as a dedicated "style" commit so it doesn't pollute feature PRs.

5. Commit .php-cs-fixer.dist.php; gitignore .php-cs-fixer.cache.

Implementation Patterns

Composer scripts are the day-to-day interface. Don't make teammates remember fixer flags:

"scripts": {
    "lint": "php-cs-fixer fix --dry-run --diff",
    "fix":  "php-cs-fixer fix"
}

composer fix locally, composer lint in CI.

CI gate (GitHub Actions). Run the dry-run as a required check so style never lands in review comments:

- run: composer install --no-interaction --prefer-dist
- run: composer lint

--dry-run exits non-zero when changes are needed, which is exactly the gate you want. Add --using-cache=no in CI (see Gotchas).

Local pre-commit hook. Either a simple composer lint hook or a captainhook/Husky entry that runs vendor/bin/php-cs-fixer fix --diff $(git diff --cached --name-only --diff-filter=ACM | grep '\.php$'). Per-file runs are much faster on large repos.

Extend, don't fork. When a project genuinely needs a deviation, layer rules on top of the package config rather than copying the ruleset:

return ChiefTools\PhpCsFixer\Config::make()
    ->setFinder($finder)
    ->setRules(array_merge(
        require __DIR__.'/vendor/chieftools/php-cs-fixer/src/rules.php', // or the documented accessor
        ['final_class' => false],
    ));

Document why each override exists — otherwise it quietly drifts from the house style.

Editor integration. Point PHPStorm's "PHP CS Fixer" inspection or the VS Code junstyle.php-cs-fixer extension at vendor/bin/php-cs-fixer and .php-cs-fixer.dist.php. Running on save keeps diffs tiny so CI stays green without a second thought.

Order in the pipeline. Format → static analysis → tests. Running the fixer before PHPStan/Larastan avoids line-shift noise in analysis output, and formatting before tests keeps stack traces aligned with committed code.

Multi-repo consistency. If you have several Chief Tools services, pin the same version across all of them ("chieftools/php-cs-fixer": "^1.0" with a shared composer.lock bump cadence). The whole value of an opinionated shared ruleset is that upgrading is a single coordinated PR, not per-repo improvisation.

Gotchas and Tips

• You are effectively the maintainer. Zero stars / zero dependents means no community bug reports, no deprecation warnings, and no guarantees. Read the config source before upgrading, and pin the major version. Consider vendoring or forking if the project is long-lived.

• Fixer version churn is the real risk. php-cs-fixer regularly renames/removes rules and flips defaults across majors. If the package doesn't constrain the fixer tightly, a composer update can change your style without any code change. Check composer why friendsofphp/php-cs-fixer and pin in CI.

• Risky rules. Opinionated rulesets usually include risky fixers (declare_strict_types, strict_comparison, void_return, etc.). If setRiskyAllowed(true) isn't set by the package, risky rules are silently ignored — easy to miss because the run still "succeeds". Verify and set explicitly if needed.

• Finder scope is the #1 footgun. ->in(__DIR__) will crawl vendor/, node_modules/, and storage/. Always enumerate source dirs and use ->exclude([...]). Forgetting this produces enormous diffs and long runtimes.

• Cache corruption / stale results. .php-cs-fixer.cache is keyed to file hashes and can go stale after branch switches. If you see "nothing to fix" on obviously unfixed code, rerun with --using-cache=no. Never commit the cache file.

• Don't run it alongside Laravel Pint. Both are php-cs-fixer wrappers with different rulesets; running both creates fight loops and noisy diffs. Pick this package for Laravel projects only if you're deliberately standardizing on Chief Tools' style; otherwise use Pint.

• Parallel + custom fixers. If the package registers custom fixers, --parallel can expose autoload order issues. Drop to single-threaded (--sequential, or PHP_CS_FIXER_FUTURE_MODE=0 in older versions) when debugging odd behavior.

• CI vs local drift. The most common "works locally, fails in CI" cause is a different fixer version resolved in CI (no lockfile, or composer update in the workflow). Use composer install from the committed lock in CI.

• Extension point: the package's config class is the seam. Subclass it or wrap it in your own App\CsFixer\Config if you need shared team-level defaults across repos — that gives you one place to bump the base ruleset later.

• Migration tip for legacy codebases: run the fixer once across the whole repo in an isolated commit, add the commit SHA to .git-blame-ignore-revs, then turn on the CI gate. Otherwise every PR drowns in formatting diffs and git blame becomes useless.