Php Cs Fixer Laravel Package

Getting Started

For a Laravel app, treat PHP CS Fixer as a dev-only formatter and CI gate—not a runtime dependency. Install it with Composer:

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

# If dependency conflicts occur, use the shim:
composer require --dev php-cs-fixer/shim

vendor/bin/php-cs-fixer init

The generated .php-cs-fixer.php is the first place to look. Customize the Finder so it only targets Laravel source directories and excludes generated files. A practical starting config:

<?php

$finder = PhpCsFixer\Finder::create()
    ->in([
        __DIR__.'/app',
        __DIR__.'/bootstrap',
        __DIR__.'/config',
        __DIR__.'/database',
        __DIR__.'/routes',
        __DIR__.'/tests',
    ])
    ->exclude(['cache', 'vendor', 'node_modules'])
    ->notName('*.blade.php');

return (new PhpCsFixer\Config())
    ->setRiskyAllowed(true)
    ->setRules([
        '@auto' => true,
        // Opt into risky sets deliberately after reviewing diffs:
        // '@auto:risky' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
        'no_unused_imports' => true,
        'single_quote' => true,
        'trailing_comma_in_multiline' => [
            'elements' => ['arrays', 'arguments', 'parameters'],
        ],
    ])
    ->setFinder($finder);

First use case: run the read-only check against app/ before fixing anything:

git status
vendor/bin/php-cs-fixer check --diff --path-mode=intersection app/

Review the diff, then apply:

vendor/bin/php-cs-fixer fix --diff --path-mode=intersection app/

check is the current read-only command; older releases use fix --dry-run --diff.

Implementation Patterns

Composer scripts are the main day-to-day interface. Add both a fix command and a CI-safe check command:

{
  "scripts": {
    "cs:check": "@php vendor/bin/php-cs-fixer check --diff --using-cache=no",
    "cs:fix": "@php vendor/bin/php-cs-fixer fix --diff"
  }
}

Then developers run composer cs:fix before committing, and CI runs composer cs:check.

Use a phased adoption path rather than fixing the entire Laravel repository at once:

1. Run check --diff on app/, review, then fix.
2. Expand to tests/, database/, routes/, config/, and bootstrap/app.php.
3. Add deliberate rule sets or risky rules one at a time, running the test suite after each change.
4. Enforce check in CI so new drift cannot merge.

Use --path-mode=intersection when passing paths. This makes the CLI path arguments intersect with the config Finder, so a command like fix app/Http/Controllers does not accidentally format files outside your configured scope.

For CI, run check-only with no cache:

- name: PHP CS Fixer
  run: composer cs:check

Use list-files to see which files need attention without applying changes:

vendor/bin/php-cs-fixer list-files

Inspect rules instead of guessing. The describe command is faster than reading the full docs:

vendor/bin/php-cs-fixer describe ordered_imports
vendor/bin/php-cs-fixer describe @autoPHPMigration

For platform upgrades, use migration sets on a dedicated branch. @autoPHPMigration and @autoPHPMigration:risky help modernize code toward newer PHP versions, and @autoPHPUnitMigration:risky helps with PHPUnit upgrades. Add them to config, run check --diff, review carefully, then run the full test suite.

Editor integration should use the same project config. PhpStorm has native support; VS Code and other editors have community plugins. Point the editor at the project PHP interpreter and .php-cs-fixer.php so format-on-save matches CLI behavior.

Do not run PHP CS Fixer and Laravel Pint with competing rule sets. Pint is Laravel’s opinionated wrapper around PHP CS Fixer. If Pint already gives you the Laravel preset you want, use Pint as the single source of truth. Use PHP CS Fixer directly when you need finer rule control, custom team conventions, or modernization sets that Pint does not expose.

Pre-commit hooks should check, not silently rewrite. A simple hook can run composer cs:check on staged PHP files and fail the commit, letting the developer run composer cs:fix and re-stage. If you auto-fix in a hook, remember the fixed files must be re-added to the index.

Gotchas and Tips

Ignore the cache file. Add .php-cs-fixer.cache to .gitignore. If results look stale after config changes, debug with --using-cache=no.

Risky rules are opt-in for a reason. setRiskyAllowed(true) allows them, but rules such as declare_strict_types, phpdoc-to-type conversions, and void_return can change runtime behavior. Enable risky sets deliberately, review --diff, and run tests. If the CLI requires it, also pass --allow-risky=yes.

Exclude Laravel-generated PHP. Do not format vendor/, node_modules/, storage/framework/views, or bootstrap/cache. Exclude *.blade.php files as well; Blade templates are not plain PHP and should not be parsed by this tool.

Start from a clean Git tree. The fixer can rewrite many files in one run. Commit or stash first, then review git diff --stat and the actual diff. Commit formatting changes separately from behavior changes.

Be careful with rule interactions and version upgrades. Fixer execution order is deterministic in current releases, but enabling overlapping sets can still produce surprising output. Pin the dependency through composer.lock; when upgrading PHP CS Fixer, run composer cs:check and review the resulting diff as a code change.

Keep the package current for new PHP syntax support. Supported PHP versions are 7.4 through 8.5. If you run on an unsupported PHP version, --allow-unsupported-php-version=yes exists but is at your own risk. Recent releases include fixes around PHP 8.4 property hooks and PHPStan/Psalm docblock types, which matters for modern Laravel projects.

Use --sequential when debugging. The parallel runner is normally fine, but if a rule interaction is hard to reproduce or CI behaves differently from local runs, run sequentially or narrow the path scope.

Prefer built-in rules and sets first. Custom fixers are possible, but day-to-day leverage comes from @auto, @auto:risky, migration sets, and a small number of team-specific rules like ordered_imports, no_unused_imports, single_quote, and trailing_comma_in_multiline. Use describe before enabling anything that rewrites docblocks or type declarations.