Usage
Usage -- Standard usage information
Getting Help from the Command Line
Running PHP_CodeSniffer with the -h or --help command line arguments will print a list of commands that PHP_CodeSniffer will respond to. The output of phpcs -h is shown below.
Usage: phpcs [-nwlvi] [--report=<report>] [--standard=<standard>]
[--config-set key value] [--config-delete key] [--config-show]
[--generator=<generator>] [--extensions=<extensions>]
[--ignore=<patterns>] [--tab-width=<width>] <file> ...
-n Do not print warnings
-w Print both warnings and errors (on by default)
-l Local directory only, no recursion
-v[v][v] Print verbose output
-i Show a list of installed coding standards
--help Print this help message
--version Print version information
<file> One or more files and/or directories to check
<extensions> A comma separated list of file extensions to check
(only valid if checking a directory)
<patterns> A comma separated list of patterns that are used
to ignore directories and files
<standard> The name of the coding standard to use
<width> The number of spaces each tab represents
<generator> The name of a doc generator to use
(forces doc generation instead of checking)
<report> Print either the "full", "xml", "checkstyle",
"csv" or "summary" report
(the "full" report is printed by default)
|
Note:
The --standard command line argument is optional, even if you have more than one coding standard installed. If no coding standard is specified, PHP_CodeSniffer will default to checking against the PEAR coding standard, or the standard you have set as the default. View instructions for setting the default coding standard.
Checking Files and Folders
The simplest way of using PHP_CodeSniffer is to provide the location of a file or folder for PHP_CodeSniffer to check. If a folder is provided, PHP_CodeSniffer will check all files it finds in that folder and all its sub-folders.
Note:
If you do not want sub-folders checked, use the -l command line argument to force PHP_CodeSniffer to run locally in the folders specified.
In the example below, the first command tells PHP_CodeSniffer to check the myfile.inc file for coding standard errors while the second command tells PHP_CodeSniffer to check all PHP files in the my_dir directory.
Checking a single file or folder
$ phpcs /path/to/code/myfile.inc
$ phpcs /path/to/code/my_dir
|
You can also specify multiple files and folders to check. The command below tells PHP_CodeSniffer to check the myfile.inc file and all files in the my_dir directory.
Checking multiple files and folders
$ phpcs /path/to/code/myfile.inc /path/to/code/my_dir
|
After PHP_CodeSniffer has finished processing your files, you will get an error report. The report lists both errors and warnings for all files that violated the coding standard. The output looks like this:
Sample PHP_CodeSniffer output
$ phpcs /path/to/code/myfile.php
FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
2 | ERROR | Missing file doc comment
20 | ERROR | PHP keywords must be lowercase; expected "false" but found
| | "FALSE"
47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
47 | WARNING | Equals sign not aligned with surrounding assignments
51 | ERROR | Missing function doc comment
88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------
|
If you don't want warnings included in the output, specify the -n command line argument.
Sample PHP_CodeSniffer output with no warnings
$ phpcs -n /path/to/code/myfile.php
FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
2 | ERROR | Missing file doc comment
20 | ERROR | PHP keywords must be lowercase; expected "false" but found "FALSE"
47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
51 | ERROR | Missing function doc comment
88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------
|
Printing a Summary Report
By default, PHP_CodeSniffer will print a complete list of all errors and warnings it finds. This list can become quite long, especially when checking a large number of files at once. To print a summary report that only shows the number of errors and warnings for each file, use the --report=summary command line argument. The output will look like this:
Sample PHP_CodeSniffer summary output
$ phpcs --report=summary /path/to/code
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/path/to/code/myfile.inc 5 0
/path/to/code/yourfile.inc 1 1
/path/to/code/ourfile.inc 0 2
--------------------------------------------------------------------------------
A TOTAL OF 6 ERROR(S) AND 3 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
|
As with the full report, you can suppress the printing of warnings with the -n command line argument.
Sample PHP_CodeSniffer summary output with no warnings
$ phpcs -n --report=summary /path/to/code
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS
--------------------------------------------------------------------------------
/path/to/code/myfile.inc 5
/path/to/code/yourfile.inc 1
--------------------------------------------------------------------------------
A TOTAL OF 6 ERROR(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
|
Printing Verbose Output
By default, PHP_CodeSniffer will run quietly, only printing the report of errors and warnings at the end. If you are checking a large number of files, you may have to wait a while to see the report. If you want to know what is happening, you can turn on verbose output.
With verbose output enabled, PHP_CodeSniffer will print the file that it is checking, show you how many tokens and lines the file contains, and let you know how long it took to process. The output will look like this:
Sample PHP_CodeSniffer verbose output
$ phpcs /path/to/code/CodeSniffer -v
Registering sniffs... DONE (22 sniffs registered)
Processing AbstractDocElement.php [1093 tokens in 303 lines]... DONE in < 1 second (0 errors, 1 warnings)
Processing AbstractParser.php [2360 tokens in 558 lines]... DONE in 2 seconds (0 errors, 1 warnings)
Processing ClassCommentParser.php [923 tokens in 296 lines]... DONE in < 1 second (2 errors, 0 warnings)
Processing CommentElement.php [988 tokens in 218 lines]... DONE in < 1 second (1 error, 5 warnings)
Processing FunctionCommentParser.php [525 tokens in 184 lines]... DONE in 1 second (0 errors, 6 warnings)
Processing File.php [10968 tokens in 1805 lines]... DONE in 5 seconds (0 errors, 5 warnings)
Processing Sniff.php [133 tokens in 94 lines]... DONE in < 1 second (0 errors, 0 warnings)
Processing SniffException.php [47 tokens in 36 lines]... DONE in < 1 second (1 errors, 3 warnings)
|
Specifying a Coding Standard
PHP_CodeSniffer can have multiple coding standards installed to allow a single installation to be used with multiple projects. When checking PHP code, PHP_CodeSniffer can be told which coding standard to use. This is done using the --standard command line argument.
The example below checks the myfile.inc file for violations of the PEAR coding standard (installed by default).
Specifying a coding standard to use
$ phpcs --standard=PEAR /path/to/code/myfile.inc
|
Printing a List of Installed Coding Standards
PHP_CodeSniffer can print you a list of the coding standards that are installed so that you can correctly specify a coding standard to use for testing. You can print this list by specifying the -i command line argument.
Generating a list of installed coding standards
$ phpcs -i
The installed coding standards are MySource, PEAR, PHPCS and Squiz.
|