How would you use PHP CS Fixer to reformat a whole PHP codebase to PER Coding Style in one commit without disrupting the team?

## The goal **PER Coding Style** is PHP-FIG's evolving coding-style specification, the successor to PSR-12. Moving an existing codebase to it with PHP CS Fixer is mechanically easy, since a single `fix` run does it. The hard part is doing it **once, predictably and reviewably**, without breaking open pull requests or `git blame` history. ## Step 1: make the result reproducible - **Pin the tool.** `composer require --dev friendsofphp/php-cs-fixer` records the exact version in `composer.lock`. Two developers on different versions can produce different output, because rule sets are not covered by the backward-compatibility promise. - **Pin the style.** `@PER-CS` is an alias for the newest revision, currently `@PER-CS3x0`. For a one-off migration, write `@PER-CS3x0` so an upgrade later cannot quietly reformat everything again. - **Commit the config.** `.php-cs-fixer.dist.php` with the Finder paths and the set, so every run selects the same files. ## Step 2: keep the commit behaviour-neutral A formatting commit is only safe to merge without line-by-line review if it **cannot change behaviour**: - no risky rules (`setRiskyAllowed(false)`, the default), so there is no `strict_comparison`, `declare_strict_types` or `native_function_invocation`; - no migration sets such as `@PHP8x5Migration` in the same commit, because those change syntax and belong in their own reviewed change; - no hand edits mixed in. The fixer lints every file it changes, and the test suite should still pass unchanged. If a test fails, something other than formatting slipped in. ## Step 3: preview, then apply 1. `vendor/bin/php-cs-fixer check --diff` shows how many files change and what the changes look like. Look for surprises, such as a vendored directory that the Finder should exclude. 2. Pick a moment when few branches are open, and announce it. 3. `vendor/bin/php-cs-fixer fix`, then run the test suite. 4. Commit with a message that says what happened, for example `style: apply PER Coding Style 3.0 with php-cs-fixer`, and push it alone. ## Step 4: protect history and open branches - **`git blame`.** Add the commit hash to a `.git-blame-ignore-revs` file and set `git config blame.ignoreRevsFile .git-blame-ignore-revs`, so blame attributes lines to their real authors and not to the formatting commit. - **Open branches.** Before rebasing onto the new base, the branch owner runs the same pinned `fix` on their branch and commits it. Their code is then formatted the same way as the new base, and most would-be conflicts disappear because both sides now contain identical lines. ## Step 5: keep it that way After the migration, the codebase stays formatted only if every new change is checked: `vendor/bin/php-cs-fixer check --diff` must pass. Where that check runs (editor, hook or pipeline) is a separate integration decision; the point here is that the commit is only the start. ## What to leave for later | Change | Why it waits | |---|---| | `@PER-CS:risky` or other risky rules | may change behaviour, so needs review and tests | | `@PHP8x5Migration` | rewrites syntax, and must match the minimum supported PHP | | moving to a newer PER revision | a deliberate future decision, so it gets its own migration commit | ## Common mistakes - **Unpinned tool.** Someone runs a newer PHP CS Fixer a week later and the "done" codebase changes again. - **Finder too wide.** Generated code, vendored libraries or fixtures that deliberately contain odd formatting get rewritten; exclude them with `exclude()` or `notPath()` first. - **Mixed commit.** A reformat that also renames a method or bumps a dependency cannot be skipped in blame or safely reverted. - **No follow-up enforcement.** Without `check` on new changes, the codebase drifts back within weeks and the next migration is needed again. ## Why one commit Reformatting file by file spreads noise across hundreds of feature commits and keeps two styles alive for months. A single, isolated commit is easy to skip in blame, easy to revert, and ends the mixed-style period at once.