PHP_CodeSniffer: Ignoring Standards

As developers, we often end up ignoring the best practices and coding standards of a programming language. This can be due to numerous reasons like ignorance, limited knowledge about standards, code readability, code maintainability, etc.

It becomes easy to write violated code and avoid coding best practices when your code is not being watched. However, the same thing becomes difficult when your code is being monitored by coding standard enforcement tools. And it becomes even more difficult when your code is being monitored by such tools plus CI systems. These systems ensure that merge requests with poor coding standards do not get merged, and instead show you errors in colours you hate.

In this blog post, we will be talking about PHP CodeSniffer, which is a tool used by PHP developers across the globe to enforce coding best practices. But apart from just enforcing code standards, this tool understands that sometimes making code violations is a legitimate need for developers to write maintainable code. And so this tool offers some provisions through which developers can make code violations, and at the same time, not throw up errors.

Below are the provisions provided by PHP CodeSniffer to ignore code violations across the different sections of the codebase:

Ignoring Parts of a File

Method 1: Ignoring a Line of Code

When To Use: This method is used to ignore some lines of violated code.

How To Use: By adding // @codingStandardsIgnoreLine before or inline with the relevant line of code.

Example: Take a look at the code sample below.

In this code snippet, Drupal 7’s translate string function called t() is used, which would ideally throw a warning when a string starting with a space is passed as an argument. However, we have overcome that by using // @codingStandardsIgnoreLine just before the line of code.

Method 2: Ignoring a Block of code

When To Use: This method is used to ignore some lines of violated code.

How To Use: By wrapping the code in // @codingStandardsIgnoreStart and // @codingStandardsIgnoreEnd.

Example: Take a look at this code sample.

In this code, the inline comments are not as per Drupal coding standards. But as a developer, writing such comments makes the code more readable. So, we’ve made violations by wrapping the code in // @codingStandardsIgnoreStart and // @codingStandardsIgnoreEnd.

Ignoring Files and Directories

Method 1: Ignoring a File

When To Use: This method is used to ignore a complete file.

How To Use: By adding the comment // @codingStandardsIgnoreFile anywhere in the file.

Example:

This code sample is of a file where all the code is related to sample configuration or APIs for documentation purposes, and so, the standards in this file have been ignored by adding // @codingStandardsIgnoreFile.

Method 2: Ignoring a Directory

When To Use: This method is used to ignore a complete directory or directories.

How To Use: By adding the --ignore argument in a PHPCS command.

Example:

The above command, when executed in the terminal, will scan all the code and directories inside the /path/to/directory/containing/files/directory except its files directory.

All the above methods work if your application is using a PHPCS version lower than 3.2.0. For changes after this version, refer to the table below:

The @codingStandards syntax was deprecated and will be removed in PHPCS version 4.0. So as a developer, if you are keeping your PHPCS version up to date, then this is an important change to implement during the update.

By following the above methods, you can ignore PHPCS rules and make as many violations as you may need. But remember: “with great power comes great responsibility”. So you should just use this technique only for valid reasons, and not treat this as your way of life as a coder.