By default, PHP_CodeSniffer will check any file it finds with a .inc or .php extension. Sometimes, this means that PHP_CodeSniffer is not checking enough of your files. Sometimes, the opposite is true. PHP_CodeSniffer allows you to specify a list of valid file extensions using the --extensions command line argument. Extensions are separated by commas.
Example 55-1. Checking .php files only
|
Example 55-2. Checking .php, .inc and .lib files only
|
Note: If you have asked PHP_CodeSniffer to check a specific file rather than an entire directory, the extension of the specified file will be ignored. The file will be checked even if it has an invalid extension or no extension at all.
In the following example, the main.inc file will be checked by PHP_CodeSniffer even though the --extensions command line argument specifies that only .php files should be checked.
Example 55-3. Extension ignored when checking specific file
$ phpcs --extensions=php /path/to/code/main.inc
Note: The ignoring of file extensions for specific files is a feature of PHP_CodeSniffer and is the only way to check files without an extension. If you check an entire directory of files, all files without extensions will be ignored, so you must check each of these file separately.
Sometimes you want PHP_CodeSniffer to run over a very large number of files, but you want some files and folders to be skipped. The --ignore command line argument can be used to tell PHP_CodeSniffer to skip files and folders that match one or more patterns.
In the following example, PHP_CodeSniffer will skip all files inside the package's tests and data directories. This is useful if you are checking a PEAR package but don't want your test or data files to conform to your coding standard.
Example 55-4. Ignoring test and data files
|
Most of the sniffs written for PHP_CodeSniffer do not support the usage of tabs for indentation and alignment. You can write your own sniffs that check for tabs instead of spaces, but you can also get PHP_CodeSniffer to convert your tabs into spaces before a file is checked. This allows you to use the existing space-based sniffs on your tab-based files.
In the following example, PHP_CodeSniffer will replace all tabs in the files being checked with between 1 and 4 spaces, depending on the column the tab indents to.
Example 55-5. Converting tabs to spaces
|
PHP_CodeSniffer can output an XML report to allow you to parse the output easily and use the results in your own scripts. To print an XML report, use the --report=xml command line argument. The output will look like this:
Example 55-6. Sample PHP_CodeSniffer XML output
|
As with the full report, you can suppress the printing of warnings with the -n command line argument.
Example 55-7. Sample PHP_CodeSniffer XML output with no warnings
|
PHP_CodeSniffer can output an XML report similar to the one produced by Checkstyle, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the --report=checkstyle command line argument. The output will look like this:
Example 55-8. Sample PHP_CodeSniffer Checkstyle output
|
As with the full report, you can suppress the printing of warnings with the -n command line argument.
Example 55-9. Sample PHP_CodeSniffer Checkstyle output with no warnings
|
PHP_CodeSniffer can output a CSV report to allow you to parse the output easily and use the results in your own scripts. To print a CSV report, use the --report=csv command line argument. The output will look like this:
Example 55-10. Sample PHP_CodeSniffer CSV output
|
As with the full report, you can suppress the printing of warnings with the -n command line argument.
Example 55-11. Sample PHP_CodeSniffer CSV output with no warnings
|
Note: The first row of the CSV output defines the order of information. When using the CSV output, please parse this header row to determine the order correctly as the format may change over time or new information may be added.
PHP_CodeSniffer has some configuration options that can be set. Individual coding standards may also require configuration options to be set before functionality can be used. View a full list of configuration options.
To set a configuration option, use the --config-set command line argument.
Example 55-12. Setting a configuration option
|
PHP_CodeSniffer allows you to delete any configuration option, reverting it to its default value. View a full list of configuration options.
To delete a configuration option, use the --config-delete command line argument.
Example 55-13. Deleting a configuration option
|
To view the currently set configuration options, use the --config-show command line argument.
Example 55-14. Viewing configuration options
|
Note: This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time.
PHP_CodeSniffer contains multiple verbosity levels. Level 2 (indicated by the command line argument -vv) will print all verbosity information for level 1 (file specific token and line counts with running times) as well as verbose tokeniser output.
The output of the PHP_CodeSniffer tokeniser shows the step-by-step creation of the scope map and the level map.
The scope map is best explained with an example. For the following file:
<?php
if ($condition) {
echo 'Condition was true';
}
?> |
The scope map output is:
Example 55-15. Sample scope map output
|
The scope map output above shows the following pieces of information about the file:
A scope token, if, was found at token 1 (note that token 0 is the open PHP tag).
The opener for the if statement, the open curly brace, was found at token 7.
The closer for the if statement, the close curly brace, was found at token 15.
Tokens 8 - 15 are all included in the scope set by the scope opener at token 7, the open curly brace. This indicates that these tokens are all within the if statement.
The scope map output is most useful when debugging PHP_CodeSniffer's scope map, which is critically important to the successful checking of a file, but is also useful for checking the type of a particular token. For example, if you are unsure of the token type for an opening curly brace, the scope map output shows you that the type is T_OPEN_CURLY_BRACKET and not, for example, T_OPEN_CURLY_BRACE.
The level map is best explained with an example. For the following file:
<?php
if ($condition) {
echo 'Condition was true';
}
?> |
The level map output is:
Example 55-16. Sample level map output
|
The level map output above shows the following pieces of information about the file:
A scope opener, an open curly brace, was found at token 7 and opened the scope for an if statement, defined at token 1.
Tokens 8 - 15 are all included in the scope set by the scope opener at token 7, the open curly brace. All these tokens are at level 1, indicating that they are enclosed in 1 scope condition, and all these tokens are enclosed in a single condition; an if statement.
The level map is most commonly used to determine indentation rules (eg. a token 4 levels deep requires 16 spaces of indentation) or to determine if a particular token is within a particular scope (eg. a function keyword is within a class scope, making it a method).
Note: This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time.
PHP_CodeSniffer contains multiple verbosity levels. Level 3 (indicated by the command line argument -vvv) will print all verbosity information for level 1 (file specific token and line counts with running times), level 2 (tokeniser output) as well as token processing output with sniff running times.
The token processing output is best explained with an example. For the following file:
<?php
if ($condition) {
echo 'Condition was true';
}
?> |
The token processing output is:
Example 55-17. Sample token processing output
|
Every token processed is shown, along with its ID, type and contents. For each token, all sniffs that were executed on the token are displayed, along with the running time.
For example, the output above shows us that token 1, an if keyword, had 3 sniffs executed on it; the ControlSignature sniff, the ScopeClosingBrace sniff and the ScopeIndent sniff. Each was executed fairly quickly, but the slowest was the ScopeClosingBrace sniff, taking 0.0248 seconds to process that token.
The other interesting piece of information we get from the output above is that only 2 tokens in the whole file had sniffs executed on them; tokens 0 and 1. This is normal behavior for PHP_CodeSniffer as most sniffs listen for a very specific and rarely used token and then execute on it and a number of tokens following it.
For example, the ScopeIndentSniff executes on the if statement's token only, but actually checks the indentation of every line within the if statement. The sniff uses the scope map to find all tokens within the if statement.