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: 1orimports.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 configandmigrate suppressionswill 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:ignorecovers 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
fixRiskyor 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).