Laravel Code Style Laravel Package

Getting Started

• Install it as a dev dependency: composer require jubeki/laravel-code-style --dev. It uses laravel/pint (and therefore PHP-CS-Fixer) as the engine, so treat Pint as an implicit dependency and keep versions aligned.
• Run the tool from the project root with ./vendor/bin/code-style. Add --test for a non-destructive check (exit code 1 when files need fixing) and --diff to preview what would change before it touches files.
• Look at the package's code-style.php config file first — that's where everything happens. It layers your extra PHP-CS-Fixer fixers on top of Pint's laravel preset. Start from the published default and add one rule at a time.
• The canonical first use case is a fixer Pint doesn't expose in pint.json — for example OrderedClassElementsFixer, PhpdocToReturnTypeFixer, HeaderCommentFixer (needs options), or community fixers from ergebnis/php-cs-fixer-custom-fixers. Add it, run code-style --diff, and confirm the change is what you expect before committing.
• Keep a composer lint / composer fix script pair so contributors don't have to remember flags: "lint": "code-style --test", "fix": "code-style".

Implementation Patterns

Config as the single source of truth. Put the config in the repo root, commit it, and let every developer and CI run the same command. Avoid passing rules ad hoc on the CLI — that's how style drift starts.

Custom fixers. Implement PhpCsFixer\Fixer\FixerInterface (usually by extending AbstractFixer or AbstractPhpdocFixer), place it under something like tools/PhpCsFixer/ or app/Support/PhpCsFixer/, and make sure the namespace is in composer.json's autoload-dev. Register it in the config by class name. If it needs configuration (e.g. a header file, a list of allowed imports), pass the options array — true will fail or do nothing useful.

Dirty-file workflow locally. Use the tool's changed-files mode (typically --dirty) in a pre-commit hook via CaptainHook or a Husky script. Run the full sweep on CI so nothing slips through. Locally, code-style --dirty --test is fast enough to run on every commit.

CI integration. In GitHub Actions, set up PHP, composer install --no-interaction, then composer lint. Cache ~/.composer/cache and the PHP-CS-Fixer cache directory to keep the job under a minute. Do not cache the working tree across branches unless you also key the cache on the config file hash.

Packages and monorepos. For a package, keep its own code-style.php next to its composer.json and run the binary from inside the package directory. For monorepos, either one root config with a finder covering all paths, or per-package configs invoked by a small loop in the root composer script — pick one and document it, because mixing both confuses everyone.

Editor integration. Because the engine is PHP-CS-Fixer, you can point PhpStorm's "PHP CS Fixer" file watcher at the same binary and config so saving a file produces the same output as running code-style. Otherwise you get a reformat war between the IDE and CI.

Gotchas and Tips

• Precedence matters. Rules from your config are merged with the Pint preset; if a rule appears in both, the preset may win or the merge may silently drop yours. When a fixer "doesn't run," first check whether the preset already defines it differently.
• Ordering and conflicts. PHP-CS-Fixer applies fixers in a fixed internal order, and some pairs fight each other (ordered_imports vs no_unused_imports, phpdoc_* vs no_superfluous_phpdoc_tags, single_quote vs heredoc_to_nowdoc). Add one fixer at a time and re-run --diff; never batch a dozen new rules into one commit.
• Config-requiring fixers. Anything that takes options (header_comment, ordered_class_elements with a custom order, class_attributes_separation) must be given an array, not true. A malformed options array often fails with a cryptic "invalid configuration" message rather than pointing at the fixer.
• Fixers that change behavior, not just style. strict_comparison, declare_strict_types, void_return, and phpdoc_to_return_type can alter runtime semantics or break callers. Review those diffs manually; don't let them ride in on an unrelated PR.
• Cache surprises. PHP-CS-Fixer caches results (.php-cs-fixer.cache). If a file you know is dirty reports clean, delete the cache or pass --clear-cache. This bites most often after switching branches or changing the config.
• --dirty and CI don't mix. In shallow clones or detached-head CI checkouts, "dirty" detection can see zero files or the wrong base. Always use the full run in CI.
• Autoloading custom fixers. If PHP-CS-Fixer can't instantiate your fixer, it usually means the class isn't autoloadable in the current working directory. Run the binary from the directory whose vendor/autoload.php contains your fixer, or move custom fixers into a properly autoloaded path.
• Exit codes are style failures, not crashes. --test exits non-zero when files need formatting; distinguish that from a PHP-CS-Fixer exception (usually a stack trace plus exit code 16 or similar) before blaming the config.
• PHP only. Blade, JSON, YAML, and frontend files are untouched — don't expect Prettier-style coverage from this tool.
• Extension points to remember: custom fixer classes, a custom preset name in the config if supported, and the underlying finder/paths. If the packaged command can't express what you need, you can always fall back to invoking PHP-CS-Fixer directly with the same config as a documented escape hatch.