PHP 8.6 is out. DressCode rewrites your code for it. Upgrading to a newer PHP →

Switch to DressCode Step by Step

Your existing suppression comments continue to work with legacy rule names, and a single command converts your configuration while highlighting anything that couldn't be carried over automatically. Here is a practical, step-by-step guide for migrating from PHP CS Fixer, PHP_CodeSniffer, or Laravel Pint, along with an honest look at what will be different.

Getting Started covers installation. The pages PHP CS Fixer, PHP_CodeSniffer and Slevomat, Nette Coding Standard and Laravel Pint add what is specific to the tool you use today.

Why It Doesn't Hurt

I know how it goes: you have a configuration refined over years of fine-tuning, hundreds of phpcs:ignore comments scattered throughout your codebase, perhaps a few custom sniffs, and a CI pipeline relying on it all. Nobody switches tools just because a new one looks shiny. You switch when the transition is painless, and that is exactly how DressCode was designed.

In DressCode, your configuration does not list rules and their options; it holds decisions: a key that names a thing in the code and a value that says how it is written, such as imports.unused: forbidden. And DressCode knows exactly which rules of PHP CS Fixer, PHP_CodeSniffer, and Slevomat each of its decisions covers. When you run dresscode catalogue, you see these rules listed with each decision in parentheses marked covers. Everything else follows from this: your existing comments in code keep working without changes, and your configuration can be translated automatically.

The switch takes five steps, and you can undo any of them at any time: a first check without touching the code, translating the configuration, the first fix, an optional rewrite of the comments, and finally replacing the old tool in CI and hooks. Subcommands of dresscode migrate take care of translating the configuration and rewriting the comments.

1. Leave the Code as It Is

Existing directives such as // phpcs:ignore, phpcs:disable, phpcs:enable, phpcs:ignoreFile, and the @phpcsSuppress annotation keep working out of the box. DressCode parses them, translates legacy rule names to its corresponding decisions on the fly, and applies the suppressions as expected. You don't have to touch your source files at all to run your very first check:

dresscode check src tests --use perCs

There is one important behavioral difference you should know: in PHP_CodeSniffer, a phpcs:ignore on a line of its own suppressed only the single line immediately following it. DressCode interprets it like its own native dresscode:ignore directive, meaning a standalone line comment applies to the entire next statement, even if it spans multiple lines. As a result, a standalone suppression comment may cover more code than it used to.

Because you don't have a configuration file yet, and DressCode checks nothing without one, the --use option supplies the standard. Choose the one that matches what you use today: perCs is PER Coding Style 3.1 (the @PER-CS set in PHP CS Fixer), psr12 is PSR-12, symfony is the @Symfony set, laravel is the default style of Pint, and nette is the Nette Coding Standard. If you had heavily customized rules beyond the standard, you will see discrepancies that the next step resolves.

2. Translate the Configuration

The migrate config command automatically locates your project's configuration, whether it belongs to PHP_CodeSniffer, PHP CS Fixer, or Laravel Pint, and writes its DressCode equivalent, including the checked paths, to dresscode.neon:

dresscode migrate config
dresscode migrate config conf/phpcs.xml --output dresscode.php

It picks the configuration your project actually uses, and when it finds several candidates, it asks; you can pass the path of another file as an argument. It never overwrites an existing file, and with --dry-run it only prints the result. If you had no configuration, or used a standard without customizations, let DressCode measure one from your code with dresscode init instead.

It looks for candidates in this order: scripts in composer.json that run a formatter with an explicit configuration file (e.g. phpcs --standard=conf/phpcs.xml, even through nested script aliases like @lint), the configuration of any formatter required in your dependencies, and files in the project root (preferring .php-cs-fixer.php over .php-cs-fixer.dist.php). Outside a terminal, it selects the first and lists the others. The file format follows the .neon or .php extension of the file in --output. Before saving, it reads the generated file the way every run reads it, to make sure it produces the translated decisions. The file belongs in your project root, as all paths it contains are relative to that root.

Translate a PHP CS Fixer configuration before you remove the old tool from the project: it is a PHP script, and migrate config runs it with the project's autoloader, and only with your permission in a terminal, see PHP CS Fixer. phpcs.xml and pint.json are read even when their tool is no longer installed.

From a phpcs.xml file that checks src and tests, builds on PSR12, enforces a 100-character line limit, flags unused imports, and requires function documentation, DressCode produces this clean dresscode.neon:

# Translated from `phpcs.xml` of PHP_CodeSniffer
# by `dresscode migrate config` of DressCode 1.5.0.
# What could not be carried over is at the end of this file.
use: psr12

paths: [src, tests]

file:
	lineLength: 100

imports:
	unused: forbidden

# Left behind by the translation. Delete this block and the comment at the top once it is dealt with.
#
# Works a little differently
#   ~ `SlevomatCodingStandard.Namespaces.UnusedUses` without `searchAnnotations` removes an import
#       only a doc comment uses; DressCode keeps it.
#
# No DressCode rule, so nothing checks these now
#   ✗ Squiz.Commenting.FunctionComment

The command reports which configuration it found, what became of your rules and, last of all, where it saved the new file:

Found `phpcs.xml` of PHP_CodeSniffer.

3 rules in your `phpcs.xml`, on the preset `psr12`:
1  carried over exactly
1  carried over, but DressCode's result may differ a little
1  dropped, DressCode has no such rule, so nothing checks them now

The details are at the end of `dresscode.neon`.
5 phpcs suppression comments: `dresscode migrate suppressions` rewrites them.
Next, `dresscode check` shows what the configuration finds in your code.

WRITTEN  dresscode.neon

The summary counts every rule once, and it names the ones you need to finish by hand. What lies behind the numbers is in the block at the end of the generated file, so it doesn't disappear when you close your terminal. Here it tells you that DressCode preserves imports referenced solely by docblocks, whereas the original sniff without searchAnnotations deleted them. Once you have dealt with the notes, delete both the block and the comment at the top of the file: they describe the migration, not your configuration. Rules without a direct counterpart are either ones you don't actually need, or ones you can easily write yourself.

A single legacy rule often maps to several granular decisions: for example, Generic.Files.LineLength with absoluteLineLimit yields file.longLines, file.lineLength, and file.lineLengthExcept. Only those the chosen standard does not already set are written to the file, which is why the example keeps just file.lineLength. Options without a DressCode counterpart are admitted in the block at the end of the file too. Rules explicitly disabled in your legacy configuration are assigned the value keep. However, if another rule from the same tool maps to that same decision, the command leaves it untouched and adds a note, since it cannot know whether one of those rules still applies. Review the generated file. It is usually pleasantly concise.

When the translation finishes, migrate config exits with code 0, whether everything came across or not. With --format json, it prints a structured document with the version in version, the project root in root, the configuration, the file it was written to, the counts of rules by what became of them, the notes, and unmapped rules; in this mode it asks no questions, just as outside a terminal.

3. The First Fix

Once your configuration is in place, run dresscode fix and commit the result in a dedicated commit with no other changes. Even when rules appear to do “the exact same thing,” automated fixes can differ in whitespace details from legacy formatters. Reviewing thousands of lines individually makes little sense; what matters is having a clean, isolated commit that contains nothing else.

In large codebases where a single massive diff is impractical, clean up incrementally by set or section: run dresscode fix --only cleanup or dresscode fix --only blankLines and commit each step separately. A final full fix will then polish the rest (see Cleaning Up Old Code Step by Step).

Anything that fix cannot resolve automatically will remain in the output. If there are more such findings than you can address today, run dresscode baseline to record them in a baseline, and only newly introduced violations will be reported.

4. Rewrite the Comments

This step is optional: legacy comments keep working. But native decision paths are shorter, consistent, and much easier to read. The summary from migrate config already told you how many directives exist across your codebase. A single command handles the rewrite:

dresscode migrate suppressions src tests

Directives like phpcs:ignore SlevomatCodingStandard.Namespaces.UnusedUses become dresscode:ignore imports.unused, phpcs:disable and phpcs:enable become dresscode:disable and dresscode:enable, and file-level phpcs:ignoreFile becomes dresscode:ignoreFile. The @phpcsSuppress annotation remains an annotation, with only the rule name updated. Whenever the command rewrites a standalone phpcs:ignore, it points out the difference in scope and the locations worth a quick manual review. Unrecognized rule names remain untouched and are listed too:

Of the 5 comments rewritten:
1  names a rule DressCode does not know, which silences nothing: `Acme.Custom.Sniff` (src/Legacy.php:12)
1  now silences the whole statement below it, not just the next line, so it may hide more than you meant (src/Legacy.php:10)

Next, replace or remove the unknown names and check what the others hide; then `dresscode check` shows the violations left.

REWRITTEN  5 comments in 1 file

You get a clear picture of the comments that suppress nothing, because DressCode does not recognize their rule, and of those that now suppress more than before. Both are things for you to review, not failures, so the command exits with code 0. It returns code 2 only when it skips a file.

With --dry-run, the command previews all replacements as a unified diff without writing changes to disk.

Only genuine directives followed immediately by a newline or comment boundary are rewritten; casual mentions of phpcs:ignore inside regular comments remain untouched. Files with syntax errors or files modified during the rewrite process are skipped, noted on the Skipped line, and trigger exit code 2. With --format json, the command prints the counts, the diffs of a run with --dry-run, and what it kept, widened and skipped, as data.

5. Replace the Old Tool in CI and Hooks

Finally, replace the old command wherever it ran: in the scripts of composer.json, in CI, in the Git hook, and in format on save in your editor. Where phpcs or php-cs-fixer fix --dry-run ran, run dresscode check, and where phpcbf, php-cs-fixer fix or pint ran, run dresscode fix. If you combined PHP_CodeSniffer and PHP CS Fixer, two steps in CI become one. Integrations shows how to set DressCode up in each of these places.

Watch out for scripts that inspect the exit code: DressCode returns 0 for clean code, 1 for findings to deal with, 2 for a failure on some file, and 3 for an error on the command line or in the configuration (see Command Line). PHP_CodeSniffer and PHP CS Fixer use their own scales, so such a script needs a minor adjustment. Then you can uninstall the old tool from the project.

What Will Be Different

A migration guide that promises a zero-friction transition loses your trust the moment you hit your first discrepancy. Here is an upfront breakdown of how things work differently:

  • Decisions instead of rules. Your configuration does not list rules and their options; it describes how your code should look: blankLines.aroundMethods: 1 or imports.unused: forbidden. Which specific rules handle the execution is DressCode's business (see Decisions Instead of Rules). The complete catalogue is available on the Rules page.
  • Priority numbers do not exist. If your previous results depended on carefully orchestrating the execution order of fixers, you may see a different shape of code in some files. DressCode executes rules in passes until the code settles (see No Priorities: Rules Run Until the Code Settles).
  • Some rules have no counterpart. Both migrate config and migrate suppressions will flag them explicitly. There are quite a few of them, primarily granular documentation sniffs and rules where the tools overlap with each other.
  • A standalone phpcs:ignore covers the whole statement, not just the next line, as the first step describes.
  • Risky fixes are permitted per decision. What PHP CS Fixer enabled only on explicit request, because it could not tell a safe case from an unsafe one on a token stream, DressCode fixes by itself where it is safe. An edit that might alter runtime behavior is reported as a risky fix and is made only after you permit it in fixRisky or with --fix-risky.

One more thing: DressCode not only formats your code, it can also rewrite it to a newer PHP and to the new API of your libraries in the same run, so you need no separate tool with its own configuration to upgrade your code (see Upgrading to a Newer PHP and Upgrading Code).

Show on GitHub · Report a problem with this page on GitHub · Nov 9, 2026