Coding Standard Laravel Package

Getting Started

Requirements check first. The package declares PHP 8.4+ as its floor. This is not just a composer.json constraint — PHP-CS-Fixer tokenizes your source with the PHP binary that runs it, so if you run it inside an old php:8.2 CI image or a Valet/Herd PHP that isn't 8.4, expect parse errors before you ever see a style fix. Confirm php -v in the exact environment where you'll run the fixer (local shell, Docker app container, CI job) before installing.

Install as a dev dependency:

composer require cline/coding-standard --dev

Pin meaningfully. This package has no dependents and a single maintainer, so treat version bumps as reviewable changes rather than floating to *:

"require-dev": { "cline/coding-standard": "^3.4" }

Where to look first, in order:

1. DOCS.md#doc-docs-basic-usage — the canonical config shape and CLI invocation. This is the source of truth; the README only advertises the features.
2. DOCS.md#doc-docs-presets — the Standard / PHPDoc / PHPUnit / Ordered presets and how they are referenced.
3. DOCS.md#doc-docs-custom-fixers — the architecture and naming fixers, which are the part most likely to disagree with your existing code.
4. CHANGELOG.md — the "standard preset removes @author / @version / license header by default" behaviour is a breaking change for teams with those policies.

Minimal config. The package ships a preconfigured finder and presets, so a .php-cs-fixer.dist.php can be short. Check DOCS.md#presets for the exact preset entry point name, then:

<?php
declare(strict_types=1);

// .php-cs-fixer.dist.php
use Cline\CodingStandard\Presets\Standard; // verify exact class/constant in DOCS.md#presets

$finder = (new PhpCsFixer\Finder())
    ->in([__DIR__.'/app', __DIR__.'/config', __DIR__.'/database', __DIR__.'/routes', __DIR__.'/tests'])
    ->exclude(['bootstrap/cache', 'storage', 'vendor', 'node_modules']);

return (new PhpCsFixer\Config())
    ->setRiskyAllowed(true)          // only if the preset contains risky rules; see Gotchas
    ->setUsingCache(true)
    ->setFinder($finder)
    ->setRules(Standard::RULES);     // or the preset's documented factory/array

If the bundled finder matches your Laravel layout, use it instead and skip the manual Finder — but add your own ->exclude() for generated artefacts you don't want rewritten (IDE helper files, bootstrap/cache/*.php, compiled views).

First run — always dry:

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

Scope it to app/ for the first pass. You want to see the shape of the diff — especially the 80-column docblock re-wrapping and any architecture fixers — before committing to a repo-wide run.

Make it a first-class command:

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

Implementation Patterns

Adopt in one style-only commit, then blind git blame to it. A first run on a Laravel app that has never been formatted produces a huge diff. Land it as a single commit that touches nothing but style, add the SHA to .git-blame-ignore-revs, and configure blame.ignoreRevsFile. This is the single highest-value habit with any PHP-CS-Fixer preset and it's what makes the churn acceptable to reviewers.

CI gate: dry-run, non-zero exit fails the build.

- name: Coding standard
  run: vendor/bin/php-cs-fixer fix --dry-run --diff --using-cache=no

--using-cache=no in CI avoids the classic stale-cache failure mode where a cached result from a different branch hides violations. Locally, keep the cache on for speed and gitignore .php-cs-fixer.cache.

Pre-commit hook: format only the staged files. A full run on every commit is too slow once app/ grows. Use path-mode intersection so the hook touches what you actually changed:

vendor/bin/php-cs-fixer fix --path-mode=intersection $(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')

Two configs, not one, for Laravel's mixed directories. PHP-CS-Fixer has no per-path rulesets. If the Standard preset enforces declare(strict_types=1) or strict class rules, you may not want that in config/, database/migrations/, or published vendor stubs. Run the fixer twice with different configs:

php-cs-fixer fix --config=.php-cs-fixer.app.php     # app/, tests/ — strict preset
php-cs-fixer fix --config=.php-cs-fixer.support.php # config/, database/ — relaxed overrides

Wire the order: Rector → fixer → tests. The bundled Rector preset (PHP 8.5 pipe-operator migrations, nested-call flattening) rewrites code; the fixer then formats the result. Do not run them in the opposite order or in parallel. Mirror the package's own just refactor → just lint → just test sequence in your composer scripts:

"refactor": "rector process",
"lint": "php-cs-fixer fix --dry-run --diff"

Editor integration. Point PhpStorm's "PHP CS Fixer" inspection or a file watcher at vendor/bin/php-cs-fixer with your .php-cs-fixer.dist.php. This gives feedback at author time, which is far cheaper than a red CI job.

Rollout across multiple repos. Keep the ruleset in one shared config file per repo but copy it from a canonical template rather than each team editing its own. For monorepos, put a .php-cs-fixer.dist.php at the root with a Finder spanning packages, and per-package overrides only where genuinely needed — config drift is the failure mode this package exists to prevent.

Opting in to the legacy fixers. The Standard preset strips @author, @version, and the file-level license header by default. If your organisation mandates license headers (legal review, open-source publishing) or tracks authorship in docblocks, re-enable the corresponding legacy fixers explicitly in your own setRules() merge rather than forking the preset.

Gotchas and Tips

PHP-CS-Fixer can't parse syntax newer than the running binary — and this package targets 8.5 features. The Rector preset enables PHP 8.5 pipe-operator migrations. If you also run the fixer under an 8.4 binary against code that Rector just rewrote with |>, tokenization fails. Run both tools on the same PHP version, and do not enable pipe-operator migration unless your runtime and every CI/deploy image is 8.5. On an 8.4 app, disable that Rector rule.

Risky rules silently block the run. PHP-CS-Fixer refuses to apply rules marked risky unless setRiskyAllowed(true) or --allow-risky=yes is set. Custom fixers are frequently risky by classification. If a rule you expect to see isn't applied and there's no error you noticed, this is the first thing to check.

The 80-column docblock wrapper is the biggest merge-conflict risk. It rewraps prose in long descriptions, @param text, and anything else that isn't a tag line. Consequences to plan for: (a) long-lived feature branches will conflict badly — land the formatting commit before branching season; (b) URLs, code samples, and ASCII tables inside docblocks get reflowed and may look worse; (c) if a developer's IDE is also set to wrap at a different width, you get a formatting war. Pick 80 everywhere or exclude your worst files.

@author / @version removal is a real policy decision, not a formatting detail. On a package with external contributors this can be contentious, and it's on by default. Decide before rollout and document it; re-enabling via the legacy fixer is cheap now and expensive after three repos have adopted.

Pint and this package will fight. Laravel Pint is a wrapper around PHP-CS-Fixer with its own preset. Running Pint after a lint run reverts rules; running both in CI produces contradictory failures. Choose one. If you keep Pint, express this package's rules in pint.json rather than running both binaries.

Expect genuine disagreements with Laravel idioms. The architecture and naming fixers are opinionated and are not Laravel-specific by design (no Blade, .env, or Artisan-aware rules ship here). Run --dry-run --diff on app/ first and expect a handful of rules that conflict with conventions you deliberately use. The fix is targeted overrides, not disabling the preset:

$rules = Standard::RULES;               // or the documented preset accessor
unset($rules['RuleName/here']);          // disable one rule
$rules['SomeOther/rule'] = ['option' => 'value'];

return (new Config())->setRules($rules)->setFinder($finder);

Keep a comment explaining why each override exists, or it will be re-added by the next person who copies the template.

Generated and stub files need excluding explicitly. _ide_helper.php, _ide_helper_models.php, bootstrap/cache/*.php, compiled Blade in storage/framework/views, and anything under public/ that isn't hand-written. Formatting them creates noise and, in the case of cache files, can break a booted app.

Don't retrofit old migrations. Formatting historical migration files rewrites files nobody should touch and pollutes blame. Exclude database/migrations from the app config or scope the fixer to new files only; new migrations get formatted normally.

Exit codes matter for CI scripts. PHP-CS-Fixer returns non-zero when files would be changed in --dry-run (distinct from a genuine error exit). Make sure your CI step distinguishes "needs formatting" from "the fixer crashed," otherwise a broken config looks like a style failure and burns an hour of debugging.

Upgrade discipline given the maturity profile. Zero stars, zero dependents, one maintainer, and presets that are explicitly opinionated: every version bump can change output. Before bumping, run php-cs-fixer fix --dry-run --diff on a clean branch and read the diff as a review artefact. Read CHANGELOG.md for removals and migration notes — the package's own maintenance rules commit to documenting breaking changes there, so that file is your upgrade safety net.

Extension points worth knowing. Beyond rule overrides, you can register your own fixers alongside the presets in the same Config object, and you can layer presets (Standard + PHPDoc + PHPUnit) rather than picking one — the Ordered preset exists precisely so combined presets land in a deterministic rule order. If you find yourself writing a custom fixer for a Laravel-specific pattern, check DOCS.md#custom-fixers first; the packaged architecture fixers may already cover it.