Skip to content

Customize PHPCS scanning

By default on VIP, PHP_CodeSniffer (PHPCS) analyzes code in all relevant files of a pull request. Additional methods and examples of the options outlined below can be found in the PHP_Codesniffer wiki.

Ignoring parts of a file

Annotations (code comments) can be added to code in a pull request to specify parts of a file for the Bot to ignore when running PHPCS. In the following examples, the specific WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase sniff is disabled rather than disabling PHPCS sniffs entirely. Selectively disabling sniffs relevant to a use case is recommended for code to benefit from analysis by the remaining PHPCS sniffs.

Ignore a single line

The phpcs:ignore annotation indicates PHPCS to ignore the code on the line where the annotation appears. In this example, the WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase sniff is ignoring line 1, and a comment ignore formatting of class name is added for explanation:

$xmlPackage = new XMLPackage; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- ignore formatting of class name

The phpcs:ignore annotation can also appear on its own line, causing the code in the following line to be ignored by PHPCS. In this example, line 2 is ignored:

// phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- ignore formatting of class name
$xmlPackage = new XMLPackage;

Ignore multiple lines

Multiple lines of code can be wrapped between the annotations phpcs:disable and phpcs:enable to prevent PHPCS from reporting violations of this code. In this example, lines 3 and 4 are ignored and the code comment disable sniff while we develop this feature notes a reason why:

// Disable a check for multiple lines,  then re-enable all checks at the end
// phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- disable sniff while we develop this feature
$xmlPackage[‘error_code’] = get_default_error_code_value();
$xmlPackage->send();
// phpcs:enable

Using the annotation // phpcs:enable without a list of sniffs ensures that readers know that all previously disabled sniffs are now enabled again.

Ignore annotations

If you want to run PHPCS and have it ignore annotations, then use the --ignore-annotations CLI parameter. This is useful to see if annotations are having an impact or if they are redundant and can be removed.

Skip PHPCS analysis or PHP Linting for specific directories

By default, the Bot scans any relevant files in pull requests using PHPCS and PHP lint. For PHPCS, both JavaScript and PHP files are analyzed for issues, while for PHP Linting, only PHP files are analyzed for syntax errors. In some cases, this can result in files being analyzed that should not, such as unit tests with deliberative syntax errors.

Directories can be selectively ignored by PHPCS analysis and PHP linting by adding files to the root of a repository:

  • Skip PHPCS analysis: Add a file named .vipgoci_phpcs_skip_folders
    Directories listed in this file, and the files that exist within them, will be ignored by PHPCS analysis.
  • Skip PHP linting: Add a file named .vipgoci_lint_skip_folders 
    Directories listed in this file, and the PHP files that exist within them, will be ignored by PHP linting.

Formatting for the .vipgoci_*_skip_folders files:

  • Directories to be ignored must be explicitly added to these lists and regular expressions are not supported.
  • List each directory to be ignored on individual lines within those files. 

In the following example, two directories are listed in .vipgoci_lint_skip_folders so that PHP linting ignores them. No PHP files in the two directories will be checked for syntax errors:

themes/news-site-theme/unit-tests
plugins/third-party-plugin-v2

Skip PHPCS scanning for specific pull requests

PHPCS analysis can be disabled for specific pull requests by adding the label skip-phpcs-scan to the pull request. Do not add any other strings or content. This label should only be used to prevent the Bot from performing PHPCS scanning on the intended pull request. 

Pull requests with this label will still be linted for PHP and may be auto-approved.

Last updated: December 26, 2023

Relevant to

  • WordPress