Php Cs Fixer Config Laravel Package

Getting Started

The package ships a shared PHP CS Fixer ruleset so every Stickee project enforces the same code style without copy-pasting a 200-line ->setRules([...]) block. It is a dev-only dependency; it does not run in production.

Install and wire it up

composer require --dev stickee/php-cs-fixer-config

Then create .php-cs-fixer.php in the project root. The exact factory name is the one thing to confirm from the README / src/ on first install, but the shape is almost always:

<?php

use PhpCsFixer\Finder;
use Stickee\PhpCsFixerConfig\Config;

$finder = Finder::create()
    ->in(__DIR__)
    ->exclude(['vendor', 'node_modules', 'storage', 'bootstrap/cache']);

return Config::make()->setFinder($finder);

Where to look first

1. README.md — the canonical snippet; copy it verbatim rather than reconstructing it.
2. src/ — usually a Config class extending PhpCsFixer\Config plus a rules array. Read the rules array; that is the actual contract you are agreeing to.
3. composer.json — check the friendsofphp/php-cs-fixer constraint. The package's supported fixer version is a hard compatibility boundary.

First use case

Audit before you fix:

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

Pipe the diff into your editor, then run fix and commit it as an isolated, style-only commit. Add both commands to composer.json immediately:

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

Implementation Patterns

Treat it as a base ruleset, not a lock. The normal day-to-day pattern is to take the shipped rules and layer project-specific ones on top:

$config = Config::make();

return $config
    ->setFinder($finder)
    ->setRules(array_merge($config->getRules(), [
        'declare_strict_types' => true,
        'final_class' => false, // our service container can't handle it
    ]));

Merge arrays rather than calling setRules() from scratch — redefining the array silently drops the Stickee baseline, and you lose future upstream fixes without noticing.

CI gate. Run cs:check in the pipeline. PHP CS Fixer exits 8 when files would change — that is your failure signal. A minimal GitHub Actions step:

- run: composer cs:check
  env:
    PHP_CS_FIXER_IGNORE_ENV: 0

Use --using-cache=no in CI so a stale cache can never mask a violation.

Pre-commit / editor loop. The highest-value pattern is not CI, it is the local loop: point your editor at .php-cs-fixer.php and enable fix-on-save. PhpStorm has a native file-watcher; VS Code users use junstyle.php-cs-fixer with "php-cs-fixer.executablePath" and "php-cs-fixer.config". Once this is on, style never enters code review again.

Directory-specific overrides. PHP CS Fixer has no per-glob ruleset in a single config. Where you genuinely need different rules (e.g. legacy app/Legacy/, or looser rules for tests/), use two config files and two CI invocations:

php-cs-fixer fix --config=.php-cs-fixer.php
php-cs-fixer fix --config=.php-cs-fixer.legacy.php

Onboarding an existing codebase. Do not sprinkle style fixes through feature PRs. Run composer cs:check once on a dedicated branch, commit the mechanical diff, then append the commit SHA to .git-blame-ignore-revs so git blame skips it. Same if you adopt a major preset upgrade.

Upgrading the preset. Bump the package, run cs:check, and read the diff before applying — a ruleset change upstream can reformat hundreds of files. Treat preset bumps as their own PR with no functional changes.

Gotchas and Tips

Pin the fixer, not just the config. The package requires a friendsofphp/php-cs-fixer version range. Letting Composer float the fixer to a new major can break the config entirely (removed/renamed fixers throw at bootstrap). If you see RuntimeException: The "%s" rule is not defined, that is a version mismatch — check the constraint rather than hacking the config.

The cache is a silent liar. .php-cs-fixer.cache persists in the project root. After changing rules or upgrading, delete it. Gitignore it. In CI, --using-cache=no.

Exit codes. 8 = fixable violations found (expected on a check), 16 = configuration error, 1 = fixer crashed on a file (often a parse error in that file — PHP CS Fixer will not fix code that doesn't tokenize). Distinguish 8 from 16 in scripts so a broken config doesn't look like a style failure.

Risky rules need opt-in. Many of the more useful rules (declare_strict_types, strict_comparison, no_unreachable_default_argument_value) are marked risky and are skipped unless the config calls setRiskyAllowed(true). Check whether the preset does this; if it doesn't, risky rules you add yourself will silently do nothing. Review risky rules before enabling, because they change runtime behaviour, not just formatting.

PHP version target. With PHP 8.x attributes, enums, and readonly promotions, the fixer needs to know your target. Ensure PHP_CS_FIXER_IGNORE_ENV is not set in production-facing CI, and that your local PHP matches the matrix — a newer local PHP plus an older fixer produces confusing partial parses.

Debugging a rule. Two commands cover almost everything:

vendor/bin/php-cs-fixer describe concat_space     # what the rule does, options, risky?
vendor/bin/php-cs-fixer fix path/to/File.php -vvv --diff

Run against a single file with -v before blaming the preset. Also confirm the file is actually matched by the Finder — files outside ->in() paths are silently ignored, which is the usual cause of "it works locally but CI fails" (symlinks, nested Composer packages, generated directories not excluded).

Excluding generated code. Add ->exclude([...]) or ->notPath(...) for compiled views, IDE stubs, _ide_helper.php, and anything in bootstrap/cache. Fixing generated files creates churn that reappears on the next build.

It is a formatter, not a linter. This package will not catch type errors, dead code, or unused imports at the semantic level. Pair it with PHPStan/Psalm and PSR-4 autoload linting in the same CI job.

Forking the preset. With only a handful of dependents, upstream response time is best-effort. If you need an org-specific tweak, add a php-cs-fixer config in your own internal package that wraps this one, rather than vendoring a copy — that keeps upstream updates mergeable.