Reporting
Printing Full and Summary Reports
See the main Usage page for basic usage information about these report types, including example output.
Both the full and summary reports can additionally show information about the source of errors and warnings. Source codes can be used with the --sniffs command line argument to only show messages from a specified list of sources. To include source codes in the report, use the -s command line argument.
Sample PHP_CodeSniffer full report with source codes
$ phpcs -s /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 (PEAR.Commenting.FileComment)
20 | ERROR | PHP keywords must be lowercase; expected "false" but found
| | "FALSE" (Generic.PHP.LowerCaseConstant)
47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
| | (PEAR.WhiteSpace.ScopeIndent)
47 | WARNING | Equals sign not aligned with surrounding assignments
| | (Generic.Formatting.MultipleStatementAlignment)
51 | ERROR | Missing function doc comment
| | (PEAR.Commenting.FunctionComment)
88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
| | (PEAR.WhiteSpace.ScopeIndent)
--------------------------------------------------------------------------------
Sample PHP_CodeSniffer summary report with source codes
$ phpcs -s --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)
--------------------------------------------------------------------------------
PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
SOURCE COUNT
--------------------------------------------------------------------------------
PEAR.WhiteSpace.ScopeIndent 3
PEAR.Commenting.FileComment 2
Generic.PHP.LowerCaseConstant 2
Generic.Formatting.MultipleStatementAlignment 1
PEAR.Commenting.FunctionComment 1
--------------------------------------------------------------------------------
A TOTAL OF 9 SNIFF VIOLATION(S) WERE FOUND IN 5 SOURCE(S)
--------------------------------------------------------------------------------
Printing a Source Report
PHP_CodeSniffer can output a summary report showing you the most common errors detected in your files so you can target specific parts of your coding standard for improvement. To print a source report, use the --report=source command line argument. The output will look like this:
Sample PHP_CodeSniffer source output
$ phpcs --report=source /path/to/code
PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
STANDARD CATEGORY SNIFF COUNT
--------------------------------------------------------------------------------
Generic PHP Lower case constant 4
PEAR White space Scope indent 3
PEAR Commenting File comment 1
--------------------------------------------------------------------------------
A TOTAL OF 8 SNIFF VIOLATION(S) WERE FOUND IN 3 SOURCE(S)
--------------------------------------------------------------------------------
To show source codes instead of friendly names, use the -s command line argument.
Sample PHP_CodeSniffer source code output
$ phpcs -s --report=source /path/to/code
PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
SOURCE COUNT
--------------------------------------------------------------------------------
Generic.PHP.LowerCaseConstant 4
PEAR.WhiteSpace.ScopeIndent 3
PEAR.Commenting.FileComment 1
--------------------------------------------------------------------------------
A TOTAL OF 8 SNIFF VIOLATION(S) WERE FOUND IN 3 SOURCE(S)
--------------------------------------------------------------------------------
Printing an XML Report
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:
Sample PHP_CodeSniffer XML output
$ phpcs --report=xml /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<phpcs version="1.0.0">
<file name="/path/to/code/myfile.php" errors="4" warnings="1">
<error line="2" column="1" source="PEAR.Commenting.FileComment" severity="5">Missing file doc comment</error>
<error line="20" column="43" source="Generic.PHP.LowerCaseConstant" severity="5">PHP keywords must be lowercase; expected "false" but found "FALSE"</error>
<error line="47" column="1" source="PEAR.WhiteSpace.ScopeIndent" severity="5">Line not indented correctly; expected 4 spaces but found 1</error>
<warning line="47" column="20" source="Generic.Formatting.MultipleStatementAlignment" severity="5">Equals sign not aligned with surrounding assignments</warning>
<error line="51" column="4" source="PEAR.Commenting.FunctionComment" severity="5">Missing function doc comment</error>
</file>
</phpcs>
Printing a Checkstyle Report
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:
Sample PHP_CodeSniffer Checkstyle output
$ phpcs --report=checkstyle /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
<file name="/path/to/code/myfile.php">
<error line="2" column="1" severity="error" message="Missing file doc comment" source="PEAR.Commenting.FileComment"/>
<error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE"" source="Generic.PHP.LowerCaseConstant"/>
<error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1" source="PEAR.WhiteSpace.ScopeIndent"/>
<error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments" source="Generic.Formatting.MultipleStatementAlignment"/>
<error line="51" column="4" severity="error" message="Missing function doc comment" source="PEAR.Commenting.FunctionComment"/>
</file>
</checkstyle>
Printing a CSV Report
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:
Sample PHP_CodeSniffer CSV output
$ phpcs --report=csv /path/to/code
File,Line,Column,Type,Message,Source,Severity
"/path/to/code/myfile.php",2,1,error,"Missing file doc comment",PEAR.Commenting.FileComment,5
"/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\"",Generic.PHP.LowerCaseConstant,5
"/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1",PEAR.WhiteSpace.ScopeIndent,5
"/path/to/code/myfile.php",47,20,warning,"Equals sign not aligned with surrounding assignments",Generic.Formatting.MultipleStatementAlignment,5
"/path/to/code/myfile.php",51,4,error,"Missing function doc comment",PEAR.Commenting.FunctionComment,5
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.
Printing an Emacs Report
PHP_CodeSniffer can output a report in a format the compiler built into the GNU Emacs text editor can understand. This lets you use the built-in complier to run PHP_CodeSniffer on a file you are editing and navigate between errors and warnings within the file. To print an Emacs report, use the --report=emacs command line argument. The output will look like this:
Sample PHP_CodeSniffer Emacs output
$ phpcs --report=emacs /path/to/code
/path/to/code/myfile.php:2:1: error - Missing file doc comment
/path/to/code/myfile.php:20:43: error - PHP keywords must be lowercase; expected "false" but found "FALSE"
/path/to/code/myfile.php:47:1: error - Line not indented correctly; expected 4 spaces but found 1
/path/to/code/myfile.php:47:20: warning - Equals sign not aligned with surrounding assignments
/path/to/code/myfile.php:51:4: error - Missing function doc comment
To use PHP_CodeSniffer with Emacs, make sure you have installed PHP mode for Emacs. Then put the following into your .emacs file, changing PHP_CodeSniffer options as required.
Sample .emacs file
(defun my-php-hook-function ()
(set (make-local-variable 'compile-command) (format "phpcs --report=emacs --standard=PEAR %s" (buffer-file-name))))
(add-hook 'php-mode-hook 'my-php-hook-function)
Now you can use the compile command and associated shortcuts to move between error messages within your file.
Printing an SVN Blame Report
PHP_CodeSniffer can make use of the svn blame command to try and determine who committed each error and warning to an SVN respository. To print an SVN Blame report, use the --report=svnblame command line argument. The output will look like this:
Sample PHP_CodeSniffer SVN Blame output
$ phpcs --report=svnblame /path/to/code
PHP CODE SNIFFER SVN BLAME SUMMARY
--------------------------------------------------------------------------------
AUTHOR COUNT (%)
--------------------------------------------------------------------------------
jsmith 51 (40.8)
jblogs 44 (30)
pdeveloper 43 (10.33)
jscript 27 (19.84)
--------------------------------------------------------------------------------
A TOTAL OF 165 SNIFF VIOLATION(S) WERE COMMITTED BY 4 AUTHOR(S)
--------------------------------------------------------------------------------
Each author is listed with the number of violations they committed and the percentage of error lines to clean lines. The example report above shows that the developer pdeveloper has 43 violations but they only make up 10% of all code they have committed, while jblogs has 44 violations but they make up 30% of all their committed code. So these developers have about the same number of total violations, but pdeveloper seems to be doing a better job of conforming to the coding standard.
To show a breakdown of the types of violations each author is committing, use the -s command line argument.
Sample PHP_CodeSniffer SVN Blame output with sources
$ phpcs -s --report=svnblame /path/to/code
PHP CODE SNIFFER SVN BLAME SUMMARY
--------------------------------------------------------------------------------
AUTHOR SOURCE COUNT (%)
--------------------------------------------------------------------------------
jsmith 51 (40.8)
Squiz.Files.LineLength 47
PEAR.Functions.FunctionCallSignature 4
jblogs 44 (30)
Squiz.Files.LineLength 40
Generic.CodeAnalysis.UnusedFunctionParameter 2
Squiz.CodeAnalysis.EmptyStatement 1
Squiz.Formatting.MultipleStatementAlignment 1
--------------------------------------------------------------------------------
A TOTAL OF 95 SNIFF VIOLATION(S) WERE COMMITTED BY 2 AUTHOR(S)
--------------------------------------------------------------------------------
To include authors with no violations, and perhaps shower them with praise, use the -v command line argument.
Sample PHP_CodeSniffer SVN Blame verbose output
$ phpcs -v --report=svnblame /path/to/code
PHP CODE SNIFFER SVN BLAME SUMMARY
--------------------------------------------------------------------------------
AUTHOR COUNT (%)
--------------------------------------------------------------------------------
jsmith 51 (40.8)
jblogs 44 (30)
pdeveloper 43 (10.33)
jscript 27 (19.84)
toogood 0 (0)
--------------------------------------------------------------------------------
A TOTAL OF 165 SNIFF VIOLATION(S) WERE COMMITTED BY 5 AUTHOR(S)
--------------------------------------------------------------------------------
You need to make sure the location of the svn command is in your path and that SVN is storing a username and password (if required by your repository). If the command is not in your path, the report will fail to generate. If SVN does not have a username and password stored, you'll need to enter it for each file being checked by PHP_CodeSniffer that contains violations.
Printing a Git Blame Report
Like the SVN Blame report, PHP_CodeSniffer can make use of the git blame command to try and determine who committed each error and warning to a Git respository. To print a Git Blame report, use the --report=gitblame command line argument. The output and options are the same as those described in the SVN Blame report above.
You need to make sure the location of the git command is in your path. If the command is not in your path, the report will fail to generate.
Printing Mutliple Reports
PHP_CodeSniffer can print any combination of the above reports to either the screen or to separate files. To print multiple reports, use the --report-[type] command line argument instead of the standard --report=[type] format. You can then specify multiple reports using multiple arguments. The reports will be printed to the screen in the order you specify them on the command line.
Writing a full and summary report to the screen
$ phpcs --report-full --report-summary /path/to/code
You can write the reports to separate files by specifying the path to the output file after each report argument.
Writing a full and summary report to a file
$ phpcs --report-full=/path/to/full.txt --report-summary=/path/to/summary.txt /path/to/code
You can print some reports to the screen and other reports to files.
Writing a full report to a file and a summary report to the screen
$ phpcs --report-full=/path/to/full.txt --report-summary /path/to/code
Running Interactively
Instead of producing a single report at the end of a run, PHP_CodeSniffer can run interactively and show reports for files one at a time. When using the interactive mode, PHP_CodeSniffer will show a report for the first file it finds an error or warning in. It will then pause and wait for user input. Once you have corrected the errors, you can press ENTER to have PHP_CodeSniffer recheck your file and continue if the file is now free of errors. You can also choose to skip the file and move to the next file with errors.
To run PHP_CodeSniffer interactively, use the -a command line argument.
Running interactively
$ phpcs -a /path/to/code
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
--------------------------------------------------------------------------------
<ENTER> to recheck, [s] to skip or [q] to quit :
PHP_CodeSniffer will always print the full error report for a file when running in interactive mode. Any report types you specify on the command line will be ignored.
Specifying a Report Width
By default, PHP_CodeSniffer will print all screen-based reports 80 characters wide. File paths will be truncated if they don't fit within this limit and error messages will be wrapped across multiple lines. You can increase the report width to show longer file paths and limit the wrapping of error messages using the -report-width command line argument.
Setting the report width to be 120 characters
$ phpcs --report-width=120 --report=summary /path/to/code/myfile.php
Writing a Report to a File
PHP_CodeSniffer always prints the specified report to the screen, but it can also be told to write a copy of the report to a file. When writing to a file, all internal parsing errors and verbose output PHP_CodeSniffer produces will not be included in the file. This feature is particularly useful when using report types such as XML and CSV that are often parsed by scripts or used with continuous integration software.
To write a copy of a report to a file, use the --report-file command line argument.
Writing a report to a file
$ phpcs --report=xml --report-file=/path/to/file.xml /path/to/code
The report will not be written to the screen when using this option. If you still want to view the report, use the -v command line argument to print verbose output.