Laravel Php Cs Fixer Laravel Package

Getting Started

Pull the package in as a dev dependency — it should never be in your production build:

composer require --dev stechstudio/laravel-php-cs-fixer

The service provider is auto-discovered, so the next thing to do is confirm the actual command name in your pinned version, since it has changed across releases:

php artisan list | grep -i cs
# typically: php-cs-fixer:fix

Before letting it rewrite anything, run it read-only on a single directory to see the blast radius:

php artisan php-cs-fixer:fix --path=app --dry-run --diff

Where to look first, in this order:

1. Does a .php-cs-fixer.php exist in the project root? If yes, it wins. The wrapper ultimately hands control to friendsofphp/php-cs-fixer, so the native config file is the source of truth.
2. The package's own config — publish it with php artisan vendor:publish (look for a php-cs-fixer tag/provider) to see what paths/preset it defaults to. If nothing is published, the command typically falls back to a small built-in path list, which will not match your app layout.
3. The pinned friendsofphp/php-cs-fixer version — composer show friendsofphp/php-cs-fixer. v2 (--allow-risky, .php_cs) and v3 (setRiskyAllowed(), .php-cs-fixer.php) differ in ways that break copy-pasted snippets.

A minimal native config that works with the v3 API:

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

return (new PhpCsFixer\Config())
    ->setRiskyAllowed(true)
    ->setRules([
        '@PSR12' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
        'no_unused_imports' => true,
        'single_quote' => true,
    ])
    ->setFinder($finder);

First real use case: run it once across app/, commit the result as a standalone chore: apply cs-fixer baseline commit with nothing else in it, and only then wire it into CI. Mixing the initial reformat with feature work makes the baseline commit unreviewable and poisons git blame.

Implementation Patterns

Wrap it in Composer scripts so nobody has to remember the artisan incantation:

"scripts": {
    "fix": "@php artisan php-cs-fixer:fix",
    "fix:check": "@php artisan php-cs-fixer:fix --dry-run --diff"
}

Scope to what changed during day-to-day work rather than reformatting the world:

php artisan php-cs-fixer:fix --path=app/Http/Controllers/InvoiceController.php
php artisan php-cs-fixer:fix --path=app/Services --path=tests/Feature

Pre-commit hook on staged files only. Pipe git diff --cached --name-only --diff-filter=ACM filtered to .php into the command via --path. Combined with a brainmaestro/composer-git-hooks or Husky setup, this keeps the diff you're about to commit clean without touching unrelated files.

CI gate. The fixer exits non-zero when files need fixing, so this is a one-liner:

- run: composer install --no-interaction --prefer-dist
- run: php artisan php-cs-fixer:fix --dry-run --diff --using-cache=no

Drop --using-cache=no in CI so a stale cache can't produce a false pass. Locally, leave the cache on — it's what makes repeated runs instant.

Editor parity. Point PhpStorm's "PHP-CS-Fixer" quality tool (or a File Watcher) at vendor/bin/php-cs-fixer and the same config file the artisan command uses. That way IDE-on-save and the CLI never disagree about import ordering.

Team rollout strategy. Introduce @PSR12 plus a handful of mechanical rules (ordered_imports, no_unused_imports, single_quote, trailing_comma_in_multiline) before adding anything behaviorally significant. Add risky rules one at a time, each in its own PR, so a declare_strict_types rollout can be reviewed on its merits rather than hidden inside a 400-file whitespace diff.

Monorepo / multi-app. Keep a config per sub-application and pass --config=packages/billing/.php-cs-fixer.php. Don't try to serve two rule sets from one finder.

Gotchas and Tips

Treat this as a thin, aging wrapper. Last tagged release was February 2022. The actual formatting logic lives in friendsofphp/php-cs-fixer, which arrives as a transitive dependency, so you can still get PHP 8.3/8.4 support via composer update friendsofphp/php-cs-fixer — but check the constraint the package declares first; if it pins ^3.0 you're fine, if it pins a minor range you're stuck. The escape hatch is trivial: delete the package and add a composer script calling vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php. Identical behavior, one less dependency. Laravel Pint is the other obvious replacement — if you adopt it, remove this package in the same PR, because two formatters fighting over the same files produce endless ping-pong diffs.

Exit codes carry meaning. 0 clean, 8 = diff found in dry-run, 4 = config error, 16 = exception. A CI step that only checks "did it crash" will happily pass code that needs fixing — make sure 8 fails the build.

Gitignore .php-cs-fixer.cache. It's written to the project root, it's machine-specific, and committing it causes spurious conflicts and stale results across branches.

Exclude resources/views. Blade templates are .php files with @directives inside; the tokenizer will either choke or mangle them. Same for _ide_helper.php, generated files, and anything under storage/.

Always use ->in() with explicit directories. A finder rooted at the project root without exclusions will walk vendor/ and node_modules/, and you'll spend twenty minutes watching it rewrite third-party code.

Verify which config file is read. The wrapper and the underlying binary have different resolution orders (.php-cs-fixer.php vs .php-cs-fixer.dist.php). If a rule you set in the config appears to be ignored, pass --config=.php-cs-fixer.php explicitly to prove the file is being loaded — that single test resolves most "the fixer is broken" reports.

Debug by bypassing the wrapper. When the artisan command gives a vague failure, run vendor/bin/php-cs-fixer fix --dry-run -vvv --config=.php-cs-fixer.php app directly. You get the real error plus per-file rule traces.

Line endings. A Windows checkout with core.autocrlf=true will produce a whole-codebase diff the first time the fixer normalizes to \n. Add * text=auto eol=lf to .gitattributes before the baseline commit, not after.

Config caching. If you published the package config and tuned paths there, remember php artisan config:clear after edits — a cached config silently ignores your change and sends the fixer at the wrong directories.

Extension point. The command is small and readable. If you need --dirty (only files changed vs main) or a --staged mode, write your own artisan command that shells out to vendor/bin/php-cs-fixer with a computed path list rather than forking the package — you keep the behavior and drop the maintenance burden.