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
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
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: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();
Using the annotation
// phpcs:enable without a list of sniffs ensures that readers know that all previously disabled sniffs are now enabled again.
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
- Skip PHPCS analysis: Add a file named
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
Directories listed in this file, and the PHP files that exist within them, will be ignored by PHP linting.
Formatting for the
- 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:
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.
Last updated: December 26, 2023