Registering Project-specific PHP_CodeSniffer Rulesets in PhpStorm

In wp-dev-lib we have followed a convention of naming our project-specific PHP_CodeSniffer rulesets as phpcs.ruleset.xml. We named the ruleset files with “phpcs” in the filename to make it clear what kind of ruleset it is, and so that it would conflict with any other tool that may also want to use this name. Nevertheless, PHP_CodeSniffer itself recognizes ruleset standards by looking for directories among its installed_paths config which contain ruleset.xml files. This hasn’t been a problem since you can specify the path to a PHP_CodeSniffer ruleset XML file by passing it as the --standard arg to phpcs:

phpcs --standard=phpcs.ruleset.xml

However, there is one issue I hadn’t figured out until now: I haven’t been able to select a project’s ruleset XML file as the standard in a PhpStorm project. PhpStorm allows you to select from among global standards that have been registered, but there is a “Custom” standard that appears at the bottom of the list:

Note the “…” button that appears next to this dropdown. It is disabled unless you select “Custom”. It opens a dialog to enter a root directory for a custom coding standard:

I think I  tried selecting this before but I must have abandoned it because I couldn’t figure out how to select a phpcs.standard.xml file. But today I did figure it out: the file directory browser allows you to select any directory that contains a ruleset.xml file.

Alternatively, instead of selecting a Custom ruleset in PhpStorm, you can also register your own rulesets as global standards which you can refer to by name. For example, consider a project “example.com” in VVV with a project directory located at /Users/johnsmith/vvv/www/example.com. If there is a ruleset.xml in this project directory, then you can register this as a global ruleset standard in PHP_CodeSniffer. To do this, you add (a bit counter-intuitively) the entire vvv/www directory to the installed_paths config. First look at your PHPCS config via phpcs --config-show. Take a note of the installed_paths. You want to add the new path to this list of paths. By default it should have ./CodeSniffer/Standards/WordPress/ so if you want to register your VVV sites root (e.g. /Users/johnsmith/vvv/www/) do:

phpcs --config-set installed_paths './CodeSniffer/Standards/WordPress/,/Users/johnsmith/vvv/www/'

Now if you run phpcs -i you should see:

The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra, WordPress-VIP and example.com

Now you can use example.com as the name of the standard from the command line, although you could have done before by passing the ruleset XML filename as the standard. But then after refreshing the rules in PhpStorm (that sync button next to the “…” button), you’ll also be able to select “example.com” as the standard for a project.

Hopefully this helps ensure your project’s coding standards are consistent across your team.