You are here

Using PHP_CodeSniffer in PhpStorm

WITTMANN Balázs Ádám's picture

PHP_CodeSniffer is a PHP5 script, which can validate PHP, JavaScript and CSS type source codes according to the different coding standards. In other words, you can easily check your source code’s standardization with a script, instead of knowing every detail about the coding standards by heart. To use PHP_CodeSniffer (referred to as phpcs later on) you have to install the script itself, and you need the coding standard’s library or file package as well. You can use phpcs in different ways, for example you can run it simply from terminal but thanks for the PhpStorm’s built-in support it becomes a much more effective tool.

Development environment

The instructions and examples you can read below were made using Ubuntu 14.04 (64 bit) operating system, PhpStorm 7.1.3, and an alpha13 version of Drupal 8.0 project (referring to differences in Drupal 7.x). If you have a different operating system, PhpStorm or Drupal version, then some things may be different from what is described here.

Coding standards

After phpcs has been installed a few coding standards like PEAR, PSR1, PSR2, Squiz or Zend are available by default, but it is possible to extend the list with further items like the Drupal coding standards.

Related rules to the Drupal coding standards are part of the Coder module. If you just want to download the coding standards for phpcs, you don’t have to install the module itself because only the standards’ directory is needed. Depending on what kind of phpcs installation and configuration you choose, it may not be necessary to download the Coder module from drupal.org (see project-level installation).

Installation types

Basically there are three ways to install and use phpcs and coding standard libraries. Differences between installation types are only logical and concerning comfort, thus whichever you choose it won’t affect on the functional behavior.

1. Project-level installation

In this case the phpcs script and the chosen coding standard library are located inside the project directory. The advantages of this solution are that the required files become portable with the project, furthermore, you have the option to use different phpcs versions and coding standard libraries for each project. However, this kind of portability also have a disadvantage because if you want to use the same version of phpcs script or a coding standard library in different projects then every project should include the related files separately (well, this is not entirely true check combined installation type). It can be a further disadvantage that the phpcs related files and libraries are not an integral part of the project because they only needed for code validation, therefore may not be necessary to put them under version control (.gitignore).

2. System-level installation

System-level installation means that the phpcs script and the coding standard library are located somewhere on the operating system level, so the point is that it is outside the project directory. In this case, if you want to use the same phpcs or coding standard library version in different projects, it is not necessary to include the related files separately in every project because they have been installed on system-level, therefore they can be used in more projects at once. Further advantage is that you don’t have to deal with the phpcs related files’ version control, because they are outside of the project directory. The problem with this kind of installation is that using different phpcs and coding standard library versions are not so comfortable this way.

3. Combined installation

This installation method (not too surprisingly) is the combination of the two mentioned previously. The most often used phpcs scripts and coding standard libraries can be installed on system-level, and you can continue to use project-level installation in special cases.

Project-level installation

Project-level installation itself is feasible in several ways but the most convenient solution is to use Composer. Composer is a dependency management tool, which allows to define dependencies for so-called packages which dependencies will be checked and installed automatically during the package installation. In this case, package means some kind of project component (like a module, a library or a script), so it is not to be confused with Unix system packages in the traditional sense.

Since Composer is working with packages and libraries it would be easy to see it as a simple package manager, but it is important that it never installs anything globally but only in project-level. Therefore, it is incorrect to define Composer as a package manager. Composer is used to install easily the phpcs script and the coding standard libraries inside the project.

Installing Composer

Composer itself can also be installed on project-level and globally too. You can find detailed descriptions about the different installation types on this page. In case of global installation on Unix systems, you just need to execute the following two simple commands:

$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

After executing the second command Composer can be easily run with the $ composer command, instead of using $ php composer.phar. If the installation of Composer was successful you should see something like this in your terminal after executing the $ composer command:

Initializing Composer

After the installation, Composer needs to be initialized. To do this, start PhpStorm and select the project’s root directory on the project management window. This step is necessary to place the downloaded files to the right place after having them downloaded by Composer. After this, select the Tools > Composer > Init Composer… menu entry, and in the popup window select the path of the composer.phar file. If you have followed the foregoing, select the /usr/local/bin/composer path.

Installing phpcs and coder packages

Composer has been installed and initialized, so now you can download packages with it. To install phpcs, select the Tools > Composer > Add dependency… menu entry and in the package selection window search for the squizlabs/php_codesniffer package.

At this point, the package version selection is important, because the phpcs script and the used coding standard library must be compatible with each other. If you are not paying attention to this, you can get various phpcs error messages later. Experience has shown, that for proper working you should install the latest and the most stable 2.x phpcs version for Drupal 8.x projects, and similarly some kind of 1.x version for Drupal 7.x projects.

Since you are working with a Drupal 8.0 project, select the 2.0.0a2 phpcs version, or a more recent one. After installing the phpcs package, search for the drupal/coder package and install it similarly.

Packages also can be installed manually if you execute the $ composer require <package name>:<version> command in the terminal (where <package name> and <version> placeholders obviously need to be replaced with the exact package name and version). Actually this command is executed when you click on the install button in the package selection window.

Configuring phpcs

Before using phpcs you have to configure its settings, which can be done at File > Settings > [Project Settings] > PHP > Code Sniffer in PhpStorm.

First, you have to tell PhpStorm where the phpcs launcher can be found. Since you have used Composer for the installation and you have a Drupal 8.0 project, the launcher can be found on the /core/vendor/bin/phpcs path inside the project directory by default. If you are working with a Drupal 7.x project instead, this path should be /vendor/bin/phpcs. After the launcher has been selected, click on the Validate button to ensure that the communication between PhpStorm and phpcs is working properly. Clicking on the Validate button is the same when executing the $ phpcs --version command to query the installed version of phpcs’s.

In additional options, you can set the maximum number of possible phpcs messages per file, and you can adjust the time PhpStorm needs to wait for the phpcs script when it is analyzing a file, so if your computer is slower it is advisable to select a higher value.

Under the above settings there is an (initially empty) list for those files which will be ignored and will not be validated by phpcs. This list can be filled if you click on the “Exclude from PHP Code Sniffer analysis” titled link in the Event log window or in the popup of the error message when some kind of phpcs error occurs during a file analysis.

Turning on the phpcs type file validation

The only remaining task is to turn on the phpcs file validation which can be done at File > Settings > [Project Settings] > Inspections > PHP > PHP Code Sniffer in PhpStorm. This option theoretically turns on the file validation for every project file (however in practice this is not always working correctly), even if they are not PHP type files because in this case they will be simply ignored. If you don’t like this general file validation, or if you want to save some CPU time, you can specify exact file extensions and directories but this will be discussed later in the file scopes section.

When enabling phpcs validation, you need to set how phpcs should display the messages and select the coding standard library you want to use. With “Severity” you can adjust the severity of the inspection that will be shown in PhpStorm. This option’s default is "Weak Warning" but it is better to set it to “Warning”. The “Show warnings as” option determines how phpcs warnings are shown. The most important setting is the “Coding standard” because this is where you can select which coding standard library you want to use for file validations. As it mentioned before, there are some coding standards which available by default but Drupal is not between them, so you have to use the “Custom” option and specify the coding standard’s path manually. Since you have installed Drupal coding standards by Composer, and you have a Drupal 8.0 project, the coding standard library should be found on the /core/vendor/drupal/coder/coder_sniffer/Drupal path inside the project. If you are working with a Drupal 7.x project, this path should be /vendor/drupal/coder/coder_sniffer/Drupal.

If all settings have been saved, phpcs will analyse and validate the files in the project automatically, according to the chosen coding standard. In PhpStorm, phpcs messages will be displayed with a “phpcs:” prefix, therefore they are easily distinguished from other types of messages.

System-level installation

In case of system-level installation the first step is to install phpcs, and then to download the coding standard library and copy or symlink it to the right place. There are several ways to install phpcs, but if you need a specific version you can easily install it with PEAR. As it mentioned in project-level installation, the selection of the appropriate phpcs version is important.

You need the execute the following command to install phpcs with PEAR:

$ sudo pear install PHP_CodeSniffer-2.0.0a2

You can check if the installation was successful by executing the $ phpcs --version command.

The second step is to download the Drupal coding standards, which is part of Coder module. Before downloading the module, make sure to select the right version. It is not necessary to install and enable the module itself, because only the coding standard library is needed from it which is located under the coder_sniffer/Drupal directory inside the module. You need to copy or symlink this whole directory into the phpcs’s standards library which is located on the /usr/share/php/PHP/CodeSniffer/Standards path if you are using Ubuntu. If you take a look into this directory, you can see that it includes a few coding standard library by default, like PEAR, PSR1, PSR2, Squiz or Zend.

Assuming that the Coder module has been downloaded (and extracted) into the /home/[username]/Downloads directory, you need to execute the following command to copy the coding standard library into the appropriate place:

$ sudo cp -Ri /home/whitelikeman/Downloads/coder/coder_sniffer/Drupal /usr/share/php/PHP/CodeSniffer/Standards

Configuring phpcs and turning on the file validation

The configuration process is almost the same as described in project-level installation, but there are some minor differences. The first is that in this case, the phpcs launcher is located outside the project directory, more specifically under the /usr/bin/phpcs path if you are using Ubuntu, therefore you have to select this path at phpcs configuration settings (File > Settings > [Project Settings] > PHP > Code Sniffer). The other difference can be found at file validation settings, because the “Drupal” option is now available in the coding standard list (if not, then click on the refresh button), so you can select it instead having to specify the path with the Custom option.

Using different versions of a coding standard library

If you prefer system-level installation, you probably want to use different versions of a coding standard library, and you would like to know them in one place (eg. in the /usr/share/php/PHP/CodeSniffer/Standards directory). Lets suppose, that you are working with a 7.x and a 8.x Drupal project at the same time, and you want to use phpcs in both cases. Of course the 7.x and 8.x Drupal coding standard libraries are different, but if you take a look to their file structure you can see that the directory and filenames are mostly the same. It may seem obvious, but it will not work if you simply rename the directories and copy them into /usr/share/php/PHP/CodeSniffer/Standards. The only “clean” workaround is to place the different standard libraries in different places, and then you can select the appropriate standard with the “Custom” option at file validation settings in PhpStorm. Theoretically you can try to rename and modify the files under the coding standard libraries, but even if it works, the update will be problematic if a new version of the standard library becomes available.

File scopes

In PhpStorm you can define so-called scopes. A scope is a group of files on which different kind of operations can be performed. At inspections (so in the case of the phpcs file validation too), you can select scopes for the inspection if you want to inspect only exact directories or files. Scopes can be managed under File > Settings > [Project Settings] > Scopes in PhpStorm.

Creating scopes

Let’s create a scope which includes any files with .inc and .php extensions under the core’s view module in a Drupal 8.0 project. Let’s name it scope_for_views. For the creation click on the “Add scope” button and in the appearing menu select the “Local” option. After the scope has been named we need to specify the file selection pattern.

During editing the file selection pattern, you can see that PhpStorm continuously counts and lists the matching files, so you can easily check if your pattern working properly. To select the previously mentioned files inside the views module use the "file:core/modules/views//*.inc||file:core/modules/views//*.php" pattern. You can find more information about the usable expressions in scope patterns on this page. After you finished editing the scope, don’t forget to save it.

Assign scopes to inspections

As it was mentioned before, inspections can be managed under File > Settings > [Project Settings] > Inspections in PhpStorm. Here you can adjust the phpcs file validation scope by right-clicking on the PHP > PHP Code Sniffer validation checkbox, and selecting the “Add scope” option. Of course, this is not only working with phpcs type file validation but with other inspections as well.

After the previously created scope_for_views scope has been selected, a scope list appears under the “PHP Code Sniffer validation” checkbox. In this list you can turn on or off each scope and you can manage phpcs messages or specify the used coding standard per scope.

Error messages

It could happen that when you try to open or edit files in PhpStorm, you get various error messages from phpcs. In these cases the most likely cause is that the installed phpcs version is not compatible with the used coding standard library. As it was mentioned in the previous sections, it is important to use compatible tools. For a 8.x Drupal project (and coding standard library) it is advisable to install the latest and the most stable 2.x phpcs version, and similarly for a 7.x Drupal project one of the 1.x versions.

Another reason behind error messages could be that the used coding standard library contains errors or bugs. This might be for example because it is just an alpha version, so try to use more stable releases. In that case if you have a slower machine, you can try to increase the “Tool process timeout” setting’s value at File > Settings > [Project Settings] > PHP > Code Sniffer to give more time for phpcs when it is analyzing files.

It is annoying, but (using PhpStorm 1.7.3) you can also get error messages when more projects are opened at the same time, and they are configured differently from phpcs aspect. It is probably a PhpStorm bug, and the only thing you can do (besides that you report the problem) is to close the projects which are currently not used, or try to use phpcs in one project at once. If something goes wrong, you can try to delete PhpStorm’s project settings directory (.idea) and restart PhpStorm.

Useful links, sources