Shift Php Cs Laravel Package

Getting Started

eduarguz/shift-php-cs packages Laravel Shift's recommended PHP-CS-Fixer ruleset as a reusable Composer dependency so you don't copy-paste a 100-line ->setRules([...]) array into every repo.

1. Install as a dev dependency (never runtime):

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

   Because the last release is 2021-12-07, check composer show eduarguz/shift-php-cs and the package's composer.json for the friendsofphp/php-cs-fixer constraint it was built against (roughly the 3.2–3.4 era). That single line tells you which fixer version to pin in your composer.json.

2. Create .php-cs-fixer.dist.php at the project root and return the package's config. The API surface is small — confirm the exact class name in vendor/eduarguz/shift-php-cs/src/ and the README — but the shape is typically:

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

3. Preview before you write:

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

   The --diff output is effectively "what Shift would touch in this repo." Skim it before running php-cs-fixer fix, because the first run on an existing codebase is noisy.

4. First use case: adopt it as one isolated style: apply Shift ruleset PR on a fresh or mature Laravel app. Land it before other work so the formatting churn doesn't mix into feature diffs.

Where to look first: the rules array inside vendor/eduarguz/shift-php-cs/src/ (that array is the product), the README's usage snippet, and composer.lock to confirm which php-cs-fixer version actually resolved.

Implementation Patterns

Wrap and override, don't fork. Get the config, then layer project-specific rules on top:

$config = Eduarguz\ShiftPhpCs\Config::create($finder);

return $config->setRules(array_merge($config->getRules(), [
    'strict_comparison' => false,     // if your codebase isn't ready
    'declare_strict_types' => false,
]));

This keeps you on the package's defaults for the 90% you don't care about.

Scope the finder, not the rules. The biggest source of pain is running the fixer over generated or vendored code. Restrict ->in([...]) to app, tests, routes, database, config and explicitly ->exclude(['bootstrap/cache', 'storage', 'public/build', 'vendor']). __DIR__ in the config file resolves to the project root because PHP-CS-Fixer requires the config be there.

CI gate on dry-run. In GitHub Actions:

- run: vendor/bin/php-cs-fixer fix --dry-run --diff --format=github

--format=github turns violations into inline PR annotations. Same trick works locally with --format=txt for humans.

Pre-commit for speed. A CaptainHook or plain .git/hooks/pre-commit running php-cs-fixer fix --path-mode=intersection <staged files> keeps diffs small between CI runs. Full-repo fixes in a hook are too slow on large apps.

Incremental adoption. On legacy code, don't fix everything at once:

git diff --name-only origin/main... | grep '\.php$' | xargs vendor/bin/php-cs-fixer fix --path-mode=intersection

Only changed files get formatted; the baseline drifts toward clean without a giant unrelated PR.

Editor integration. Point PhpStorm's "PHP CS Fixer" inspection and VS Code's junstyle.php-cs-fixer extension at the same .php-cs-fixer.dist.php. Same rules locally and in CI eliminates the "works on my machine" formatting argument.

Consider Laravel Pint first. Pint (Laravel 9+) is the official, maintained, opinionated wrapper around PHP-CS-Fixer and ships with Laravel. Reach for shift-php-cs when you specifically want Shift's historical ruleset or you're on a pre-Pint app. On a new Laravel project, Pint is the lower-maintenance choice.

Gotchas and Tips

The package is a 2021 snapshot, not a living standard. With 11 stars and a single historical release, treat it as "Shift's opinion, frozen at v1." If you want long-term stability, copy the rules array out of vendor/ into your own config and own it. That's a one-time 5-minute job and buys you permanent control.

Version skew is the #1 failure mode. PHP-CS-Fixer 3.x renames and deprecates rules between minors. Installing a recent 3.x against a 2021-era rules array will emit Rule ... is deprecated warnings or throw Unknown rule. Fix by pinning the fixer to the version the package was authored against, or by updating the offending rule keys in your overrides.

setRiskyAllowed(true) is required for @PhpCsFixer:risky-style rules. Shift's config enables risky rules (e.g. declare_strict_types, strict_comparison, void_return). If you return a bare new Config() and forget this, the fixer aborts with a clear but easy-to-miss error. If it's already baked into the package's factory, leave it; if you override the config, keep it.

Commit or ignore .php-cs-fixer.cache. The fixer writes a cache file at the project root. Add it to .gitignore; it changes on every run and creates pointless merge conflicts if committed.

Rule ordering is handled by the fixer, not by your array order. Don't reorder rules hoping to change behavior; if two rules conflict, the fixer reports it in --dry-run --diff -v. That's your debugging path — verbose plus diff.

PHP_CS_FIXER_IGNORE_ENV=1 is a last resort. It silences the PHP-version-mismatch warning when your runtime PHP is newer than the fixer supports. Use it only to unblock CI temporarily; the real fix is bumping the fixer or downgrading PHP in the lint job.

Run the lint job on a PHP version the fixer supports, not necessarily your production PHP. A separate lint matrix entry (e.g. PHP 8.0/8.1 for a 2021 fixer) is safer than coupling style checks to your deploy runtime.

Extension points are just Config. Because everything composes through PhpCsFixer\Config, any customization — rule overrides, setUsingCache(false), setIndent(' ') — is done by chaining on the returned config. There's no event system or plugin API to learn.

Debugging a single file is usually faster than a whole-repo run:

vendor/bin/php-cs-fixer fix app/Http/Controllers/FooController.php --dry-run --diff -vvv