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

Comments can be added to code in a pull request in order 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 in order for code to benefit from analysis by other remaining PHPCS sniffs.

Ignore a single line

The phpcs:ignore comment indicates PHPCS to ignore the code on the line in which the comment 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 comment 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 comments phpcs:disable and phpcs:enable in order to prevent PHPCS from reporting errors for 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

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 PHP linted and it is possible for them to be auto approved.

Last updated: October 27, 2022