Cs Laravel Package

Getting Started

This is a small, single-maintainer coding-standard package (2 stars, no dependents), so the first job is to find out exactly what it wraps before you wire it into anything.

1. Inspect before installing. Open composer.json on the repo and check the require / require-dev block. That tells you whether it is a PHP CS Fixer config, a Laravel Pint preset, a PHP_CodeSniffer ruleset, or an ECS config — the day-to-day commands differ completely between those. Then read src/ (usually a handful of files: a Config class or a rules.php / .php-cs-fixer.dist.php you are meant to require).
2. Install as a dev dependency only, and pin it:

   composer require --dev jrmajor/cs:^1.0
   

   With zero dependents and a personal-project release cadence, an unpinned ^ on a 0.x tag will eventually break CI on a Tuesday.
3. Do a dry run on one directory first. Never let a new ruleset touch app/ and tests/ on the same commit:

   vendor/bin/php-cs-fixer fix app --dry-run --diff --using-cache=no
   # or
   vendor/bin/pint --test app
   

   Read the diff. Ten minutes here tells you more about the package's opinions than any README.
4. First real use case: adopt it on new code only. Point the config at a single new module/service directory, get that clean, commit, and expand outward later. Do not open with a repo-wide reformat — the diff will be unreviewable and will bury every open branch.

Implementation Patterns

Composer scripts as the single entry point. Give the team two verbs and make everything else call them:

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

Then CI, pre-commit hooks, and humans all invoke composer cs, so switching the underlying tool later is a one-line change.

CI as an enforcement gate, not a fixer. In GitHub Actions, run the dry-run variant on the changed paths and fail the job on a non-zero exit. Keep caching on (.php-cs-fixer.cache keyed on the PHP version + lockfile hash) or the job gets slow enough that people start skipping it.

Publish/extend rather than fork. If the package ships a config you require, create your own .php-cs-fixer.dist.php that imports theirs and then merges project-specific rules on top. Rules are applied in order and later entries win, so your overrides must come after the require. This is the intended extension point and it survives package upgrades far better than copying their rules file into your repo.

Tiered strictness by path. One ruleset for app/, a looser one for tests/ and database/migrations/, and no fixing at all under vendor/, storage/, bootstrap/cache/, and generated files. Most config formats let you declare multiple finder blocks with different rule sets.

Layer it with static analysis, not instead of it. CS tools only touch whitespace, imports, and syntax shape. Pair with PHPStan/Larastan and (optionally) Rector. Order in CI: cs → phpstan → tests, cheapest first so formatting nits fail fast.

Pre-commit hook for the files that changed. A lint-staged-style invocation (php-cs-fixer fix --path-mode=intersection <staged files>) keeps commits clean without a repo-wide pass. GrumPHP or CaptainHook are the usual Laravel-side wrappers.

Editor alignment. Install the PHP CS Fixer (or Pint) extension in PhpStorm/VS Code, point it at your project config, enable format-on-save. If you skip this, developers will hand-format to their own habits and the CI job becomes a nag rather than a tool.

Gotchas and Tips

• Verify the tool identity before writing docs. The single most common failure with a package this small is assuming it's a Pint preset when it's actually a PHP CS Fixer config (or vice versa). The commands, config file names, and cache files are all different. Read composer.json; do not guess from the package name.
• Pin and review upgrades manually. Zero dependents means you are the de facto QA. Treat version bumps as code review events, run --dry-run --diff across the whole repo, and read the changelog. composer update in a lockfile-refresh PR is how surprise reformats land.
• Rule ordering matters. In fixer configs, conflicting rules resolve to the last one declared. A rule you add "for one file" can silently override the package's opinion everywhere if you put it in the wrong block.
• Cache files bite. .php-cs-fixer.cache is keyed on file hashes and the ruleset; stale caches after a config change produce "no changes" lies. Add --using-cache=no when debugging, and gitignore the cache (or commit it deliberately — just pick one, don't let it flip-flop).
• Paths are relative to the config file, not the CWD. Running the binary from a subdirectory with a --config pointing elsewhere is a classic source of "it fixed nothing" confusion.
• Exit codes in CI. Dry-run mode returns non-zero when files would change. That is the desired behavior — but don't wrap it in || true to "make CI green," and don't run the fixing variant in CI (it will pass while leaving the working tree dirty and silently discarded).
• Keep it out of production. --dev install, and exclude the binary from any deploy artifact. It has no runtime role.
• Don't fight the IDE. If Prettier/Tailwind formatting or a Pint install already runs on save, you now have two formatters rewriting the same lines. Pick one owner per file type and disable the other.
• Extension points to reach for, in order: (1) your own config that requires theirs and appends rules; (2) a custom fixer class registered with the tool for project-specific patterns (e.g. house-style docblocks); (3) a fork — last resort, and only if the maintainer is unresponsive, since you inherit maintenance permanently.
• Budget for abandonment. A 2-star, single-maintainer package is a personal standard published for convenience. Before adopting, confirm the ruleset is expressed as plain config you could vendor into your repo in an afternoon. If it isn't, keep it out of your critical path.