Php Cs Fixer Config Laravel Package

Getting Started

This package is a shared PHP-CS-Fixer configuration, not an application dependency. You add it as a dev dependency and it gives you a single source of truth for code style instead of copy-pasting .php-cs-fixer.dist.php between projects.

composer require --dev webproject-xyz/php-cs-fixer-config

Where to look first: open vendor/webproject-xyz/php-cs-fixer-config/ and read its README plus the top-level source file — the entry point is usually a config factory or a Config subclass that returns a pre-populated PhpCsFixer\Config (finder, rules, risky flags). Confirm the exact class name there before writing your config; don't guess it from the package name.

First use case: create .php-cs-fixer.dist.php in the project root, point the factory at your source directories, and run it on a single file to sanity-check before touching the whole repo:

<?php

declare(strict_types=1);

use PhpCsFixer\Finder;
// use the factory/class documented in the package README

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

return /* package config */->setFinder($finder);

vendor/bin/php-cs-fixer fix app/Http/Controllers/UserController.php --diff

Then commit the dist config and add composer scripts so the team has one entry point:

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

Implementation Patterns

Compose, don't fork. Treat the package's ruleset as a base and layer project-specific overrides on top. This keeps you upgradeable:

$config = (package config)->setFinder($finder);

$config->setRules(array_merge($config->getRules(), [
    'declare_strict_types' => true,
    'final_class' => false, // project disagrees with the default
]));

return $config;

CI gate on pull requests. Run the dry-run form in CI so violations fail the build, with cache disabled to avoid stale results on ephemeral runners:

vendor/bin/php-cs-fixer fix --dry-run --diff --using-cache=no --ansi

For large monorepos/PRs, restrict scope to changed files in CI to keep feedback fast:

vendor/bin/php-cs-fixer fix --dry-run --diff \
  --path-mode=intersection $(git diff --name-only origin/main...HEAD -- '*.php')

Pre-commit hook. Wire composer fix into Captain Hook, simple-git-hooks, or a plain .git/hooks/pre-commit so style never reaches CI. Prefer fixing only staged files here — a whole-repo fix on every commit is slow and produces noisy diffs.

Editor parity. Point PhpStorm/VS Code PHP CS Fixer integrations at vendor/bin/php-cs-fixer and the project's .php-cs-fixer.dist.php. Editor-on-save and CI must resolve the same installed version, otherwise you get format ping-pong on files nobody meaningfully changed.

Parallel fixing for local runs. On a decently sized codebase, --parallel is a large wall-clock win locally. Keep it off in CI dry-run mode if you're diffing per-file to keep output readable.

Baseline adoption on legacy code. If the ruleset produces a huge first diff, run the fix once as its own commit with only formatting changes, add it to .git-blame-ignore-revs, and only then enable the CI gate. Don't mix the mass reformat with functional changes.

Gotchas and Tips

This release (1.1.3) is a dependency/constraint bump — the risk is transitive, not in the package's own code. Bumping deps very likely moves friendsofphp/php-cs-fixer forward too. PHP-CS-Fixer deprecates and renames fixers regularly, and a fixer's default behaviour can change between minor versions. After upgrading, always run composer fix --dry-run --diff and review the churn before committing — a "patch" release can still reformat your codebase.

Your lockfile won't move unless you ask it to. composer update webproject-xyz/php-cs-fixer-config --with-dependencies gets you the bumped transitive fixer. A plain composer update on an unrelated package won't.

Check the PHP constraint before upgrading. The release explicitly bumps the PHP constraint. If your app still supports an older PHP minor in CI, that job will fail to install. Diagnose with:

composer why-not webproject-xyz/php-cs-fixer-config 1.1.3

If you're genuinely stuck on an older PHP, stay pinned at 1.1.2 — this is a tooling package, so lagging a patch is low-risk.

Risky rules need opt-in. Many useful fixers are marked @risky and are silently skipped unless ->setRiskyAllowed(true) is set. If a rule you configured appears to do nothing, that's usually why. Note that some package configs enable this for you; check before assuming.

Finder exclusions are on you. Forgetting storage/, bootstrap/cache/, or compiled Blade views leads to the fixer rewriting generated files or crawling slowly. Also add .php-cs-fixer.cache to .gitignore — it's a binary-ish cache file that causes merge noise if committed.

Never commit the cache across branches/CI. A stale cache can mask violations on changed files. Use --using-cache=no in CI; keep the cache locally for speed.

Rule ordering and conflicts. Two fixers touching the same construct (e.g. import ordering vs. fully_qualified_strict_types) can fight each other and produce diffs that flip on every run. If --dry-run reports the same file repeatedly after a fix, you have a conflicting pair — remove one rather than debugging it repeatedly.

Extension point worth knowing: because the package exposes a real PhpCsFixer\Config, everything PHP-CS-Fixer offers (setRules, setFinder, setRiskyAllowed, setCacheFile, header comments) remains available. You should almost never need to fork the package — compose on top of it, and feed disagreements back upstream so every project benefits.