Registering Project-specific PHP_CodeSniffer Rulesets in PhpStorm

Authored by

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:

PhpStorm PHP_CodeSniffer Custom standard

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:

PhpStorm select PHPCS Custom

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.

4 thoughts on “Registering Project-specific PHP_CodeSniffer Rulesets in PhpStorm”

  1. I am facing the exact problem since I don’t want to rename the phpcs standard file to ruleset.xml

    Were you able to figure out a solution to the problem without renaming the file?

      1. Actually I was about PHPStorm 🙂

        My ruleset XML is named `phpcs.xml`. I can’t find a way to use this custom ruleset with PhpStorm, unless I rename it to ruleset.xml.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.