cvs: peardoc /en/package/php/php-codesniffer advanced-usage.xml config-options.xml faq.xml intro.xml reporting.xml usage.xml
| From: | Greg Sherwood | Date: | Mon, 22 Dec 2008 04:00:39 +0000 |
| Subject: | cvs: peardoc /en/package/php/php-codesniffer advanced-usage.xml config-options.xml faq.xml intro.xml reporting.xml usage.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-11336@lists.php.net to get a copy of this message | ||
squiz Mon Dec 22 04:00:39 2008 UTC
Added files:
/peardoc/en/package/php/php-codesniffer reporting.xml
Modified files:
/peardoc/en/package/php/php-codesniffer advanced-usage.xml
config-options.xml faq.xml
intro.xml usage.xml
Log:
Updated docs for version 1.2.0a1
http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/advanced-usage.xml?r1=1.9&r2=1.10&diff_format=u Index: peardoc/en/package/php/php-codesniffer/advanced-usage.xml diff -u peardoc/en/package/php/php-codesniffer/advanced-usage.xml:1.9 peardoc/en/package/php/php-codesniffer/advanced-usage.xml:1.10 --- peardoc/en/package/php/php-codesniffer/advanced-usage.xml:1.9 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/advanced-usage.xml Mon Dec 22 04:00:39 2008 @@ -6,28 +6,21 @@ </refnamediv> <refsection xml:id="package.php.php-codesniffer.advanced-usage.valid-file-extensions"><info><title>Specifying Valid File Extensions</title></info> - <para> By default, PHP_CodeSniffer will check any file it finds with a <literal>.inc</literal> or <literal>.php</literal> 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 <literal>--extensions</literal> command line argument. Extensions are separated by commas. </para> <example><info><title>Checking <literal>.php</literal> files only</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --extensions=php /path/to/code ]]> - </userinput> </screen> </example> <example><info><title>Checking <literal>.php</literal>, <literal>.inc</literal> and <literal>.lib</literal> files only</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --extensions=php,inc,lib /path/to/code ]]> - </userinput> </screen> </example> <note> @@ -38,13 +31,10 @@ In the following example, the main.inc file will be checked by PHP_CodeSniffer even though the <literal>--extensions</literal> command line argument specifies that only <literal>.php</literal> files should be checked. </simpara> <example><info><title>Extension ignored when checking specific file</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --extensions=php /path/to/code/main.inc ]]> - </userinput> </screen> </example> </note> @@ -56,10 +46,7 @@ </refsection> - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.ignore-files-folders"><info><title>Ignoring Files and Folders</title></info> - <para> 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 <literal>--ignore</literal> command line argument can be used to tell PHP_CodeSniffer to skip files and folders that match one or more patterns. </para> @@ -67,188 +54,52 @@ In the following example, PHP_CodeSniffer will skip all files inside the package's <filename>tests</filename> and <filename>data</filename> 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. </para> <example><info><title>Ignoring test and data files</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --ignore=*/tests/*,*/data/* /path/to/code ]]> - </userinput> </screen> </example> </refsection> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.replace-tabs-spaces"><info><title>Replacing Tabs with Spaces</title></info> - - <para> - 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. - </para> + <refsection xml:id="package.php.php-codesniffer.advanced-usage.sniffs"><info><title>Limiting Results to Specific Sniffs</title></info> <para> - 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. + By default, PHP_CodeSniffer will ceck your code using all sniffs in the specified standard. Sometimes you may want to find all occcurances of an error to eliminate it more quickly or understand the scope of the problem. PHP_CodeSniffer allows you to specify a list of sniffs to limit results to using the <literal>--sniffs</literal> command line argument. Sniffs are separated by commas. </para> - <example><info><title>Converting tabs to spaces</title></info> - + <example><info><title>Checking files for two specific sniffs only</title></info> <screen> - <userinput> <![CDATA[ -$ phpcs --tab-width=4 /path/to/code -]]> - </userinput> - </screen> - </example> - </refsection> - - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.xml-report"><info><title>Printing an XML Report</title></info> - - <para> - 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 <literal>--report=xml</literal> command line argument. The output will look like this: - </para> - <example><info><title>Sample PHP_CodeSniffer XML output</title></info> - - <screen> -<![CDATA[ -$ 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="5" warnings="1"> - <error line="2" column="1">Missing file doc comment</error> - <error line="20" column="43">PHP keywords must be lowercase; expected "false" but found "FALSE"</error> - <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error> - <warning line="47" column="20">Equals sign not aligned with surrounding assignments</warning> - <error line="51" column="4">Missing function doc comment</error> - <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error> - </file> -</phpcs> -]]> - </screen> - </example> - <para> - As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. - </para> - <example><info><title>Sample PHP_CodeSniffer XML output with no warnings</title></info> - - <screen> -<![CDATA[ -$ phpcs -n --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="5" warnings="0"> - <error line="2" column="1">Missing file doc comment</error> - <error line="20" column="43">PHP keywords must be lowercase; expected "false" but found "FALSE"</error> - <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error> - <error line="51" column="4">Missing function doc comment</error> - <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error> - </file> -</phpcs> -]]> - </screen> - </example> - </refsection> - - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.checkstyle-report"><info><title>Printing a Checkstyle Report</title></info> - - <para> - PHP_CodeSniffer can output an XML report similar to the one produced by <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://checkstyle.sourceforge.net/">Checkstyle</link>, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the <literal>--report=checkstyle</literal> command line argument. The output will look like this: - </para> - <example><info><title>Sample PHP_CodeSniffer Checkstyle output</title></info> - - <screen> -<![CDATA[ -$ 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"/> - <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE""/> - <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/> - <error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments"/> - <error line="51" column="4" severity="error" message="Missing function doc comment"/> - <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/> - </file> -</checkstyle> -]]> - </screen> - </example> - <para> - As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. - </para> - <example><info><title>Sample PHP_CodeSniffer Checkstyle output with no warnings</title></info> - - <screen> -<![CDATA[ -$ phpcs -n --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"/> - <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE""/> - <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/> - <error line="51" column="4" severity="error" message="Missing function doc comment"/> - <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/> - </file> -</checkstyle> +$ phpcs --sniffs=Generic.PHP.LowerCaseConstant,PEAR.WhiteSpace.ScopeIndent /path/to/code ]]> </screen> </example> + <note> + <simpara> + To view source codes for error messages, use the <literal>-s</literal> command line argument. This will print source codes in the full, summary and source reports. + </simpara> + </note> </refsection> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.csv-report"><info><title>Printing a CSV Report</title></info> - + <refsection xml:id="package.php.php-codesniffer.advanced-usage.replace-tabs-spaces"><info><title>Replacing Tabs with Spaces</title></info> <para> - 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 <literal>--report=csv</literal> command line argument. The output will look like this: + 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. </para> - <example><info><title>Sample PHP_CodeSniffer CSV output</title></info> - - <screen> -<![CDATA[ -$ phpcs --report=csv /path/to/code - -File,Line,Column,Severity,Message -"/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" -"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6" -]]> - </screen> - </example> <para> - As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. + 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. </para> - <example><info><title>Sample PHP_CodeSniffer CSV output with no warnings</title></info> - + <example><info><title>Converting tabs to spaces</title></info> <screen> <![CDATA[ -$ phpcs -n --report=csv /path/to/code - -File,Line,Column,Severity,Message -"/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",51,4,error,"Missing function doc comment" -"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6" +$ phpcs --tab-width=4 /path/to/code ]]> </screen> </example> - <note> - <simpara> - 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. - </simpara> - </note> </refsection> <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-set"><info><title>Setting Configuration Options</title></info> - <para> 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. <link linkend="package.php.php-codesniffer.config-options">View a full list of configuration options.</link> </para> @@ -258,49 +109,39 @@ <example><info><title>Setting a configuration option</title></info> <screen> - <userinput> <![CDATA[ $ phpcs --config-set <option> <value> ]]> - </userinput> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-delete"><info><title>Deleting Configuration Options</title></info> - <para> PHP_CodeSniffer allows you to delete any configuration option, reverting it to its default value. - <link linkend="package.php.php-codesniffer.config-options">View a full list of configuration options.</link> </para> <para> To delete a configuration option, use the <literal>--config-delete</literal> command line argument. </para> <example><info><title>Deleting a configuration option</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --config-delete <option> ]]> - </userinput> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-show"><info><title>Viewing Configuration Options</title></info> - <para> To view the currently set configuration options, use the <literal>--config-show</literal> command line argument. </para> <example><info><title>Viewing configuration options</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --config-show Array @@ -309,17 +150,12 @@ [zend_ca_path] => /path/to/ZendCodeAnalyzer ) ]]> - </userinput> </screen> </example> </refsection> - - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-tokeniser-output"><info><title>Printing Verbose Tokeniser Output</title></info> - <note> <simpara> This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time. @@ -331,9 +167,7 @@ <para> The output of the PHP_CodeSniffer tokeniser shows the step-by-step creation of the <emphasis>scope map</emphasis> and the <emphasis>level map</emphasis>. </para> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-tokeniser-output.scope-map"><info><title>The Scope Map</title></info> - <para> The scope map is best explained with an example. For the following file: </para> @@ -352,7 +186,6 @@ The scope map output is: </para> <example><info><title>Sample scope map output</title></info> - <screen> <![CDATA[ *** START SCOPE MAP *** @@ -396,9 +229,7 @@ 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 <constant>T_OPEN_CURLY_BRACKET</constant> and not, for example, <constant>T_OPEN_CURLY_BRACE</constant>. </para> </refsection> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-tokeniser-output.level-map"><info><title>The Level Map</title></info> - <para> The level map is best explained with an example. For the following file: </para> @@ -417,7 +248,6 @@ The level map output is: </para> <example><info><title>Sample level map output</title></info> - <screen> <![CDATA[ *** START LEVEL MAP *** @@ -464,31 +294,17 @@ 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 <literal>function</literal> keyword is within a class scope, making it a method). </para> </refsection> - </refsection> - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-token-processing-output"><info><title>Printing Verbose Token Processing Output</title></info> - <note> <simpara> - This feature is provided for debugging purposes only. - - Using this feature will dramatically increase screen output and script running time. + This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time. </simpara> </note> <para> - PHP_CodeSniffer contains multiple verbosity levels. - - Level 3 (indicated by the command line argument - <literal>-vvv</literal>) - 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. + PHP_CodeSniffer contains multiple verbosity levels. Level 3 (indicated by the command line argument <literal>-vvv</literal>) 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. </para> <para> The token processing output is best explained with an example. For the following file: @@ -509,7 +325,6 @@ </para> <para> <example><info><title>Sample token processing output</title></info> - <screen> <![CDATA[ *** START TOKEN PROCESSING *** http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/config-options.xml?r1=1.7&r2=1.8&diff_format=u Index: peardoc/en/package/php/php-codesniffer/config-options.xml diff -u peardoc/en/package/php/php-codesniffer/config-options.xml:1.7 peardoc/en/package/php/php-codesniffer/config-options.xml:1.8 --- peardoc/en/package/php/php-codesniffer/config-options.xml:1.7 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/config-options.xml Mon Dec 22 04:00:39 2008 @@ -6,15 +6,11 @@ </refnamediv> <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer"><info><title>PHP_CodeSniffer Configuration Options</title></info> - - <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.default-standard"><info><title>Setting the Default Coding Standard</title></info> - <para> By default, PHP_CodeSniffer will use the <emphasis>PEAR</emphasis> coding standard if no standard is supplied on the command line. You can change the default standard by setting the <literal>default_standard</literal> configuration option. </para> <example><info><title>Setting the default standard to be the Zend coding standard</title></info> - <screen> <userinput> <![CDATA[ @@ -25,13 +21,12 @@ </example> </refsection> + <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.report-format"><info><title>Setting the Default Report Format</title></info> - <para> By default, PHP_CodeSniffer will use the <emphasis>full</emphasis> report format if no format is supplied on the command line. You can change the default report format by setting the <literal>report_format</literal> configuration option. </para> <example><info><title>Setting the default report format to be the summary report</title></info> - <screen> <userinput> <![CDATA[ @@ -42,13 +37,12 @@ </example> </refsection> + <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.show-warnings"><info><title>Hiding Warnings by Default</title></info> - <para> By default, PHP_CodeSniffer will show both errors and warnings for your code. You can hide warnings for a single script run by using the <literal>-n</literal> command line argument, but you can also enable this by default if you prefer. To hide warnings by default, set the <literal>show_warnings</literal> configuration option to <literal>0</literal>. </para> <example><info><title>Hiding warnings by default</title></info> - <screen> <userinput> <![CDATA[ @@ -64,13 +58,12 @@ </note> </refsection> + <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.tab-width"><info><title>Setting the Default Tab Width</title></info> - <para> By default, PHP_CodeSniffer will not convert tabs to spaces in checked files. Specifying a tab width will make PHP_CodeSniffer replace tabs with spaces. You can force PHP_CodeSniffer to replace tabs with spaces by default by setting the <literal>tab_width</literal> configuration option. </para> <example><info><title>Setting the default tab width to be 4 spaces</title></info> - <screen> <userinput> <![CDATA[ @@ -84,7 +77,6 @@ When the tab width is set by default, the replacement of tabs with spaces can be disabled for a single script run by setting the tab width to zero. </simpara> <example><info><title>Disabling the replacement of tabs with spaces</title></info> - <screen> <userinput> <![CDATA[ @@ -95,22 +87,41 @@ </example> </note> </refsection> - </refsection> - - <refsection xml:id="package.php.php-codesniffer.config-options.squiz"><info><title>Squiz Coding Standard Configuration Options</title></info> - - + <refsection xml:id="package.php.php-codesniffer.config-options.squiz.jslint-path"><info><title>Setting the Path to JSLint</title></info> + <para> + The Squiz coding standard includes a sniff that will check each JavaScript file using <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.jslint.com/">JSLint</link>, a JavaScript program that looks for problems in JavaScript programs. Use the <literal>jslint_path</literal> configuration option to tell the JSLint sniff where to find the tool. + </para> + <example><info><title>Setting the path to JSLint</title></info> + <screen> + <userinput> +<![CDATA[ +$ phpcs --config-set jslint_path /path/to/jslint.js +]]> + </userinput> + </screen> + </example> + <para> + As JSLint is just JavaScript code, you alos need to install <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.mozilla.org/rhino/">Rhino</link> to be able to execute it. Use the <literal>rhino_path</literal> configuration option to tell the JSLint sniff where to find the tool. + </para> + <example><info><title>Setting the path to Rhino</title></info> + <screen> + <userinput> +<![CDATA[ +$ phpcs --config-set rhino_path /path/to/rhino +]]> + </userinput> + </screen> + </example> + </refsection> <refsection xml:id="package.php.php-codesniffer.config-options.squiz.jsl-path"><info><title>Setting the Path to JavaScript Lint</title></info> - <para> The Squiz coding standard includes a sniff that will check each JavaScript file using <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.javascriptlint.com">JavaScript Lint</link>, a tool that checks all your JavaScript source code for common mistakes without actually running the script or opening the web page. Use the <literal>jsl_path</literal> configuration option to tell the JavaScript Lint sniff where to find the tool. </para> <example><info><title>Setting the path to JavaScript Lint</title></info> - <screen> <userinput> <![CDATA[ @@ -120,22 +131,15 @@ </screen> </example> </refsection> - </refsection> - - <refsection xml:id="package.php.php-codesniffer.config-options.zend"><info><title>Zend Coding Standard Configuration Options</title></info> - - <refsection xml:id="package.php.php-codesniffer.config-options.zend.zend-ca-path"><info><title>Setting the Path to the Zend Code Analyzer</title></info> - <para> The Zend coding standard includes a sniff that will check each file using the Zend Code Analyzer, a tool that comes with Zend Studio. Use the <literal>zend_ca_path</literal> configuration option to tell the Zend Code Analyzer sniff where to find the tool. </para> <example><info><title>Setting the path to the Zend Code Analyzer</title></info> - <screen> <userinput> <![CDATA[ @@ -145,7 +149,6 @@ </screen> </example> </refsection> - </refsection> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/faq.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/en/package/php/php-codesniffer/faq.xml diff -u peardoc/en/package/php/php-codesniffer/faq.xml:1.5 peardoc/en/package/php/php-codesniffer/faq.xml:1.6 --- peardoc/en/package/php/php-codesniffer/faq.xml:1.5 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/faq.xml Mon Dec 22 04:00:39 2008 @@ -6,14 +6,12 @@ </refnamediv> <refsection><info><title>Does PHP_CodeSniffer perform any code coverage or unit testing?</title></info> - <para> No. PHP_CodeSniffer is not a tool for testing that your PHP application works correctly. All PHP_CodeSniffer will do is ensure your PHP code meets the standards that you are following. </para> </refsection> <refsection><info><title>My code is fine! Why do I need PHP_CodeSniffer?</title></info> - <para> Maybe you don't, but if you want to ensure you adhere to a set of coding standards, PHP_CodeSniffer is a quick and easy way to do that. PHP_CodeSniffer is a replacement for the more manual task of checking coding standards in code reviews. With PHP_CodeSniffer, you can reserve code reviews for the checking of code correctness. </para> @@ -25,7 +23,6 @@ </refsection> <refsection><info><title>Does PHP_CodeSniffer parse my code to ensure it will execute?</title></info> - <para> No. PHP_CodeSniffer does not actually parse your code, and so cannot accurately tell if your code contains parse errors. PHP_CodeSniffer does know about some parse errors and will warn you if it finds code that it is unable to sniff correctly due to a suspected parse error. However, as there is no actual parsing taking place, PHP_CodeSniffer may return an incorrect number of errors when checking code that does contain parse errors. </para> @@ -45,14 +42,12 @@ </refsection> <refsection><info><title>I don't agree with your coding standards! Can I make PHP_CodeSniffer enforce my own?</title></info> - <para> Yes. At its core, PHP_CodeSniffer is just a framework for enforcing coding standards. We release PHP_CodeSniffer with some sample coding standards to help developers get started on projects where there is no standard defined. If you want to write your own standard, read the <link linkend="package.php.php-codesniffer.coding-standard-tutorial">tutorial on creating coding standards</link>. </para> </refsection> <refsection><info><title>How come PHP_CodeSniffer reported errors, I fixed them, now I get even more?</title></info> - <para> Sometimes, errors mask the existence of other errors, or new errors are created as you fix others. For example, PHP_CodeSniffer might tell you that an inline IF statement needs to be defined with braces. Once you make this change, PHP_CodeSniffer may report that the braces you added are not correctly aligned. </para> @@ -62,9 +57,8 @@ </refsection> <refsection><info><title>Why doesn't PHP_CodeSniffer just make the changes it suggests for me?</title></info> - <para> - As much as we trust PHP_CodeSniffer to check your code for coding standard errors, we don't trust any application to ever change code for us without reviewing it first. Considering we would have to check each change PHP_CodeSniffer made before releasing the source code, why not make the changes manually? + As much as we trust PHP_CodeSniffer to check your code for coding standard errors, we don't trust any application to ever change code for us without reviewing it first. Considering you would have to check each change PHP_CodeSniffer made before releasing the source code, why not make the changes manually? </para> <para> Making the changes manually ensures a couple of positive things happen: @@ -90,10 +84,12 @@ </note> </refsection> - <refsection><info><title>What does PHP_CodeSniffer use to tokenize my PHP code?</title></info> - + <refsection><info><title>What does PHP_CodeSniffer use to tokenize my code?</title></info> <para> - PHP_CodeSniffer uses <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.php.net/tokenizer">PHP's inbuilt tokenizer functions</link> to parse your PHP code. + For PHP files, PHP_CodeSniffer uses <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.php.net/tokenizer">PHP's inbuilt tokenizer functions</link> to parse your code. It then changes that output to include much more data about the file, such as matching function braces to function keywords. + </para> + <para> + For all other file types, PHP_CodeSniffer includes a custom tokenizer that either makes use of PHP's inbuilt tokenizer or emulates it. In both cases, the token array must be checked and changed manually before all the standard PHP_CodeSniffer matching rules are applied, making tokenizing a bit slower for these file types. </para> </refsection> http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/intro.xml?r1=1.6&r2=1.7&diff_format=u Index: peardoc/en/package/php/php-codesniffer/intro.xml diff -u peardoc/en/package/php/php-codesniffer/intro.xml:1.6 peardoc/en/package/php/php-codesniffer/intro.xml:1.7 --- peardoc/en/package/php/php-codesniffer/intro.xml:1.6 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/intro.xml Mon Dec 22 04:00:39 2008 @@ -6,17 +6,17 @@ </refnamediv> <refsection><info><title>Description</title></info> - + <para> - PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP and JavaScript code to detect violations of a defined coding standard. It is an essential development tool that ensures your code remains clean and consistent. It can also help prevent some common semantic errors made by developers. + PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP, JavaScript and CSS files to detect violations of a defined coding standard. It is an essential development tool that ensures your code remains clean and consistent. It can also help prevent some common semantic errors made by developers. </para> <para> - A coding standard, in PHP_CodeSniffer, is a collection of <emphasis>sniff</emphasis> files. Each sniff file checks one part of the coding standard only. Multiple coding standards can be used within PHP_CodeSniffer, so that the one installation can be used across multiple projects. The default coding standard used by PHP_CodeSniffer is the <emphasis>PEAR</emphasis> coding standard. + A coding standard in PHP_CodeSniffer is a collection of <emphasis>sniff</emphasis> files. Each sniff file checks one part of the coding standard only. Multiple coding standards can be used within PHP_CodeSniffer so that the one installation can be used across multiple projects. The default coding standard used by PHP_CodeSniffer is the <emphasis>PEAR</emphasis> coding standard. </para> </refsection> <refsection><info><title>Example</title></info> - + <para> To check a file against the PEAR coding standard, simply specify the file's location. </para> http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/usage.xml?r1=1.13&r2=1.14&diff_format=u Index: peardoc/en/package/php/php-codesniffer/usage.xml diff -u peardoc/en/package/php/php-codesniffer/usage.xml:1.13 peardoc/en/package/php/php-codesniffer/usage.xml:1.14 --- peardoc/en/package/php/php-codesniffer/usage.xml:1.13 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/usage.xml Mon Dec 22 04:00:39 2008 @@ -6,20 +6,21 @@ </refnamediv> <refsection xml:id="package.php.php-codesniffer.usage.getting-help"><info><title>Getting Help from the Command Line</title></info> - <para> Running PHP_CodeSniffer with the <literal>-h</literal> or <literal>--help</literal> command line arguments will print a list of commands that PHP_CodeSniffer will respond to. The output of <literal>phpcs -h</literal> is shown below. </para> <para> <screen> <![CDATA[ -Usage: phpcs [-nwlvi] [--report=<report>] [--standard=<standard>] +Usage: phpcs [-nwlsvi] [--report=<report>] [--report-file=<reportfile>] [--config-set key value] [--config-delete key] [--config-show] - [--generator=<generator>] [--extensions=<extensions>] - [--ignore=<patterns>] [--tab-width=<width>] <file> ... + [--standard=<standard>] [--sniffs=<sniffs>] + [--extensions=<extensions>] [--ignore=<patterns>] + [--generator=<generator>] [--tab-width=<width>] <file> ... -n Do not print warnings -w Print both warnings and errors (on by default) -l Local directory only, no recursion + -s Show sniff codes in all reports -v[v][v] Print verbose output -i Show a list of installed coding standards --help Print this help message @@ -29,13 +30,17 @@ (only valid if checking a directory) <patterns> A comma separated list of patterns that are used to ignore directories and files + <sniffs> A comma separated list of sniff codes to limit the check to + (all sniffs must be part of the specified standard) <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 + "csv", "emacs", "source" or "summary" report (the "full" report is printed by default) + <reportfile> Write the report to the specified file path + (report is also written to screen) ]]> </screen> @@ -49,7 +54,6 @@ <refsection xml:id="package.php.php-codesniffer.usage.checking-files-folders"><info><title>Checking Files and Folders</title></info> - <para> 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. </para> @@ -62,7 +66,6 @@ In the example below, the first command tells PHP_CodeSniffer to check the <filename>myfile.inc</filename> file for coding standard errors while the second command tells PHP_CodeSniffer to check all PHP files in the <filename>my_dir</filename> directory. </para> <example><info><title>Checking a single file or folder</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/myfile.inc @@ -74,7 +77,6 @@ You can also specify multiple files and folders to check. The command below tells PHP_CodeSniffer to check the <filename>myfile.inc</filename> file and all files in the <filename>my_dir</filename> directory. </para> <example><info><title>Checking multiple files and folders</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/myfile.inc /path/to/code/my_dir @@ -85,7 +87,6 @@ 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: </para> <example><info><title>Sample PHP_CodeSniffer output</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/myfile.php @@ -109,7 +110,6 @@ If you don't want warnings included in the output, specify the <literal>-n</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer output with no warnings</title></info> - <screen> <![CDATA[ $ phpcs -n /path/to/code/myfile.php @@ -131,12 +131,10 @@ <refsection xml:id="package.php.php-codesniffer.usage.summary-report"><info><title>Printing a Summary Report</title></info> - <para> 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 <literal>--report=summary</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer summary output</title></info> - <screen> <![CDATA[ $ phpcs --report=summary /path/to/code @@ -158,7 +156,6 @@ As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer summary output with no warnings</title></info> - <screen> <![CDATA[ $ phpcs -n --report=summary /path/to/code @@ -179,7 +176,6 @@ <refsection xml:id="package.php.php-codesniffer.usage.verbose-output"><info><title>Printing Verbose Output</title></info> - <para> 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. </para> @@ -187,7 +183,6 @@ 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: </para> <example><info><title>Sample PHP_CodeSniffer verbose output</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/CodeSniffer -v @@ -207,7 +202,6 @@ <refsection xml:id="package.php.php-codesniffer.usage.coding-standard"><info><title>Specifying a Coding Standard</title></info> - <para> 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 <literal>--standard</literal> command line argument. </para> @@ -228,12 +222,10 @@ <refsection xml:id="package.php.php-codesniffer.usage.installed-standards"><info><title>Printing a List of Installed Coding Standards</title></info> - <para> 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 <literal>-i</literal> command line argument. </para> <example><info><title>Generating a list of installed coding standards</title></info> - <screen> <![CDATA[ $ phpcs -i http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/reporting.xml?view=markup&rev=1.1 Index: peardoc/en/package/php/php-codesniffer/reporting.xml +++ peardoc/en/package/php/php-codesniffer/reporting.xml <?xml version="1.0" encoding="utf-8"?> <refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.php.php-codesniffer.reporting"> <refnamediv> <refname>Reporting</refname> <refpurpose>Report types and options</refpurpose> </refnamediv> <refsection><info><title>Printing Full and Summary Reports</title></info> <note> <simpara> See the main <link linkend="package.php.php-codesniffer.usage">usage</link> page for basic usage information about these report types, including example output. </simpara> </note> <para> Both the full and summary reports can additionally show information about the source of errors and warnings. Source codes can be used with the <literal>--sniffs</literal> command line argument to only show messages from a specified list of sources. To include source codes in the report, use the <literal>-s</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer full report with source codes</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> <example><info><title>Sample PHP_CodeSniffer summary report with source codes</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.source-report"><info><title>Printing a Source Report</title></info> <para> 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 <literal>--report=source</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer source output</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> <para> To show source codes instead of friendly names, use the <literal>-s</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer source code output</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.xml-report"><info><title>Printing an XML Report</title></info> <para> 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 <literal>--report=xml</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer XML output</title></info> <screen> <![CDATA[ $ 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">Missing file doc comment</error> <error line="20" column="43" source="Generic.PHP.LowerCaseConstant">PHP keywords must be lowercase; expected "false" but found "FALSE"</error> <error line="47" column="1" source="PEAR.WhiteSpace.ScopeIndent">Line not indented correctly; expected 4 spaces but found 1</error> <warning line="47" column="20" source="Generic.Formatting.MultipleStatementAlignment">Equals sign not aligned with surrounding assignments</warning> <error line="51" column="4" source="PEAR.Commenting.FunctionComment">Missing function doc comment</error> </file> </phpcs> ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.checkstyle-report"><info><title>Printing a Checkstyle Report</title></info> <para> PHP_CodeSniffer can output an XML report similar to the one produced by <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://checkstyle.sourceforge.net/">Checkstyle</link>, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the <literal>--report=checkstyle</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer Checkstyle output</title></info> <screen> <![CDATA[ $ 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> ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.csv-report"><info><title>Printing a CSV Report</title></info> <para> 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 <literal>--report=csv</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer CSV output</title></info> <screen> <![CDATA[ $ phpcs --report=csv /path/to/code File,Line,Column,Severity,Message,Source "/path/to/code/myfile.php",2,1,error,"Missing file doc comment",PEAR.Commenting.FileComment "/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\"",Generic.PHP.LowerCaseConstant "/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1",PEAR.WhiteSpace.ScopeIndent "/path/to/code/myfile.php",47,20,warning,"Equals sign not aligned with surrounding assignments",Generic.Formatting.MultipleStatementAlignment "/path/to/code/myfile.php",51,4,error,"Missing function doc comment",PEAR.Commenting.FunctionComment ]]> </screen> </example> <note> <simpara> 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. </simpara> </note> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.emacs-report"><info><title>Printing an Emacs Report</title></info> <para> 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 <literal>--report=emacs</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer Emacs output</title></info> <screen> <![CDATA[ $ 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 ]]> </screen> </example> <para> To use PHP_CodeSniffer with Emacs, make sure you have installed <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://php-mode.sourceforge.net/">PHP mode for Emacs</link>. Then put the following into your <filename>.emacs</filename> file, changing PHP_CodeSniffer options as required. </para> <example><info><title>Sample .emacs file</title></info> <screen> <![CDATA[ (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) ]]> </screen> </example> <para> Now you can use the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation.html">compile command</link> and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-Mode.html">associated shortcuts</link> to move between error messages within your file. </para> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.report-file"><info><title>Writing a Report to a File</title></info> <para> 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. </para> <para> To write a copy of a report to a file, use the <literal>--report-file</literal> command line argument. Note that a copy of the report will also be written to the screen. </para> <example><info><title>Writing a report to a file</title></info> <screen> <![CDATA[ $ phpcs --report=xml --report-file=/path/to/file.xml /path/to/code ]]> </screen> </example> </refsection> </refentry>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/advanced-usage.xml?r1=1.9&r2=1.10&diff_format=u Index: peardoc/en/package/php/php-codesniffer/advanced-usage.xml diff -u peardoc/en/package/php/php-codesniffer/advanced-usage.xml:1.9 peardoc/en/package/php/php-codesniffer/advanced-usage.xml:1.10 --- peardoc/en/package/php/php-codesniffer/advanced-usage.xml:1.9 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/advanced-usage.xml Mon Dec 22 04:00:39 2008 @@ -6,28 +6,21 @@ </refnamediv> <refsection xml:id="package.php.php-codesniffer.advanced-usage.valid-file-extensions"><info><title>Specifying Valid File Extensions</title></info> - <para> By default, PHP_CodeSniffer will check any file it finds with a <literal>.inc</literal> or <literal>.php</literal> 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 <literal>--extensions</literal> command line argument. Extensions are separated by commas. </para> <example><info><title>Checking <literal>.php</literal> files only</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --extensions=php /path/to/code ]]> - </userinput> </screen> </example> <example><info><title>Checking <literal>.php</literal>, <literal>.inc</literal> and <literal>.lib</literal> files only</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --extensions=php,inc,lib /path/to/code ]]> - </userinput> </screen> </example> <note> @@ -38,13 +31,10 @@ In the following example, the main.inc file will be checked by PHP_CodeSniffer even though the <literal>--extensions</literal> command line argument specifies that only <literal>.php</literal> files should be checked. </simpara> <example><info><title>Extension ignored when checking specific file</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --extensions=php /path/to/code/main.inc ]]> - </userinput> </screen> </example> </note> @@ -56,10 +46,7 @@ </refsection> - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.ignore-files-folders"><info><title>Ignoring Files and Folders</title></info> - <para> 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 <literal>--ignore</literal> command line argument can be used to tell PHP_CodeSniffer to skip files and folders that match one or more patterns. </para> @@ -67,188 +54,52 @@ In the following example, PHP_CodeSniffer will skip all files inside the package's <filename>tests</filename> and <filename>data</filename> 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. </para> <example><info><title>Ignoring test and data files</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --ignore=*/tests/*,*/data/* /path/to/code ]]> - </userinput> </screen> </example> </refsection> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.replace-tabs-spaces"><info><title>Replacing Tabs with Spaces</title></info> - - <para> - 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. - </para> + <refsection xml:id="package.php.php-codesniffer.advanced-usage.sniffs"><info><title>Limiting Results to Specific Sniffs</title></info> <para> - 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. + By default, PHP_CodeSniffer will ceck your code using all sniffs in the specified standard. Sometimes you may want to find all occcurances of an error to eliminate it more quickly or understand the scope of the problem. PHP_CodeSniffer allows you to specify a list of sniffs to limit results to using the <literal>--sniffs</literal> command line argument. Sniffs are separated by commas. </para> - <example><info><title>Converting tabs to spaces</title></info> - + <example><info><title>Checking files for two specific sniffs only</title></info> <screen> - <userinput> <![CDATA[ -$ phpcs --tab-width=4 /path/to/code -]]> - </userinput> - </screen> - </example> - </refsection> - - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.xml-report"><info><title>Printing an XML Report</title></info> - - <para> - 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 <literal>--report=xml</literal> command line argument. The output will look like this: - </para> - <example><info><title>Sample PHP_CodeSniffer XML output</title></info> - - <screen> -<![CDATA[ -$ 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="5" warnings="1"> - <error line="2" column="1">Missing file doc comment</error> - <error line="20" column="43">PHP keywords must be lowercase; expected "false" but found "FALSE"</error> - <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error> - <warning line="47" column="20">Equals sign not aligned with surrounding assignments</warning> - <error line="51" column="4">Missing function doc comment</error> - <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error> - </file> -</phpcs> -]]> - </screen> - </example> - <para> - As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. - </para> - <example><info><title>Sample PHP_CodeSniffer XML output with no warnings</title></info> - - <screen> -<![CDATA[ -$ phpcs -n --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="5" warnings="0"> - <error line="2" column="1">Missing file doc comment</error> - <error line="20" column="43">PHP keywords must be lowercase; expected "false" but found "FALSE"</error> - <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error> - <error line="51" column="4">Missing function doc comment</error> - <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error> - </file> -</phpcs> -]]> - </screen> - </example> - </refsection> - - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.checkstyle-report"><info><title>Printing a Checkstyle Report</title></info> - - <para> - PHP_CodeSniffer can output an XML report similar to the one produced by <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://checkstyle.sourceforge.net/">Checkstyle</link>, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the <literal>--report=checkstyle</literal> command line argument. The output will look like this: - </para> - <example><info><title>Sample PHP_CodeSniffer Checkstyle output</title></info> - - <screen> -<![CDATA[ -$ 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"/> - <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE""/> - <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/> - <error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments"/> - <error line="51" column="4" severity="error" message="Missing function doc comment"/> - <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/> - </file> -</checkstyle> -]]> - </screen> - </example> - <para> - As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. - </para> - <example><info><title>Sample PHP_CodeSniffer Checkstyle output with no warnings</title></info> - - <screen> -<![CDATA[ -$ phpcs -n --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"/> - <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE""/> - <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/> - <error line="51" column="4" severity="error" message="Missing function doc comment"/> - <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/> - </file> -</checkstyle> +$ phpcs --sniffs=Generic.PHP.LowerCaseConstant,PEAR.WhiteSpace.ScopeIndent /path/to/code ]]> </screen> </example> + <note> + <simpara> + To view source codes for error messages, use the <literal>-s</literal> command line argument. This will print source codes in the full, summary and source reports. + </simpara> + </note> </refsection> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.csv-report"><info><title>Printing a CSV Report</title></info> - + <refsection xml:id="package.php.php-codesniffer.advanced-usage.replace-tabs-spaces"><info><title>Replacing Tabs with Spaces</title></info> <para> - 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 <literal>--report=csv</literal> command line argument. The output will look like this: + 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. </para> - <example><info><title>Sample PHP_CodeSniffer CSV output</title></info> - - <screen> -<![CDATA[ -$ phpcs --report=csv /path/to/code - -File,Line,Column,Severity,Message -"/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" -"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6" -]]> - </screen> - </example> <para> - As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. + 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. </para> - <example><info><title>Sample PHP_CodeSniffer CSV output with no warnings</title></info> - + <example><info><title>Converting tabs to spaces</title></info> <screen> <![CDATA[ -$ phpcs -n --report=csv /path/to/code - -File,Line,Column,Severity,Message -"/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",51,4,error,"Missing function doc comment" -"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6" +$ phpcs --tab-width=4 /path/to/code ]]> </screen> </example> - <note> - <simpara> - 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. - </simpara> - </note> </refsection> <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-set"><info><title>Setting Configuration Options</title></info> - <para> 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. <link linkend="package.php.php-codesniffer.config-options">View a full list of configuration options.</link> </para> @@ -258,49 +109,39 @@ <example><info><title>Setting a configuration option</title></info> <screen> - <userinput> <![CDATA[ $ phpcs --config-set <option> <value> ]]> - </userinput> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-delete"><info><title>Deleting Configuration Options</title></info> - <para> PHP_CodeSniffer allows you to delete any configuration option, reverting it to its default value. - <link linkend="package.php.php-codesniffer.config-options">View a full list of configuration options.</link> </para> <para> To delete a configuration option, use the <literal>--config-delete</literal> command line argument. </para> <example><info><title>Deleting a configuration option</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --config-delete <option> ]]> - </userinput> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-show"><info><title>Viewing Configuration Options</title></info> - <para> To view the currently set configuration options, use the <literal>--config-show</literal> command line argument. </para> <example><info><title>Viewing configuration options</title></info> - <screen> - <userinput> <![CDATA[ $ phpcs --config-show Array @@ -309,17 +150,12 @@ [zend_ca_path] => /path/to/ZendCodeAnalyzer ) ]]> - </userinput> </screen> </example> </refsection> - - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-tokeniser-output"><info><title>Printing Verbose Tokeniser Output</title></info> - <note> <simpara> This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time. @@ -331,9 +167,7 @@ <para> The output of the PHP_CodeSniffer tokeniser shows the step-by-step creation of the <emphasis>scope map</emphasis> and the <emphasis>level map</emphasis>. </para> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-tokeniser-output.scope-map"><info><title>The Scope Map</title></info> - <para> The scope map is best explained with an example. For the following file: </para> @@ -352,7 +186,6 @@ The scope map output is: </para> <example><info><title>Sample scope map output</title></info> - <screen> <![CDATA[ *** START SCOPE MAP *** @@ -396,9 +229,7 @@ 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 <constant>T_OPEN_CURLY_BRACKET</constant> and not, for example, <constant>T_OPEN_CURLY_BRACE</constant>. </para> </refsection> - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-tokeniser-output.level-map"><info><title>The Level Map</title></info> - <para> The level map is best explained with an example. For the following file: </para> @@ -417,7 +248,6 @@ The level map output is: </para> <example><info><title>Sample level map output</title></info> - <screen> <![CDATA[ *** START LEVEL MAP *** @@ -464,31 +294,17 @@ 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 <literal>function</literal> keyword is within a class scope, making it a method). </para> </refsection> - </refsection> - - <refsection xml:id="package.php.php-codesniffer.advanced-usage.verbose-token-processing-output"><info><title>Printing Verbose Token Processing Output</title></info> - <note> <simpara> - This feature is provided for debugging purposes only. - - Using this feature will dramatically increase screen output and script running time. + This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time. </simpara> </note> <para> - PHP_CodeSniffer contains multiple verbosity levels. - - Level 3 (indicated by the command line argument - <literal>-vvv</literal>) - 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. + PHP_CodeSniffer contains multiple verbosity levels. Level 3 (indicated by the command line argument <literal>-vvv</literal>) 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. </para> <para> The token processing output is best explained with an example. For the following file: @@ -509,7 +325,6 @@ </para> <para> <example><info><title>Sample token processing output</title></info> - <screen> <![CDATA[ *** START TOKEN PROCESSING *** http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/config-options.xml?r1=1.7&r2=1.8&diff_format=u Index: peardoc/en/package/php/php-codesniffer/config-options.xml diff -u peardoc/en/package/php/php-codesniffer/config-options.xml:1.7 peardoc/en/package/php/php-codesniffer/config-options.xml:1.8 --- peardoc/en/package/php/php-codesniffer/config-options.xml:1.7 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/config-options.xml Mon Dec 22 04:00:39 2008 @@ -6,15 +6,11 @@ </refnamediv> <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer"><info><title>PHP_CodeSniffer Configuration Options</title></info> - - <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.default-standard"><info><title>Setting the Default Coding Standard</title></info> - <para> By default, PHP_CodeSniffer will use the <emphasis>PEAR</emphasis> coding standard if no standard is supplied on the command line. You can change the default standard by setting the <literal>default_standard</literal> configuration option. </para> <example><info><title>Setting the default standard to be the Zend coding standard</title></info> - <screen> <userinput> <![CDATA[ @@ -25,13 +21,12 @@ </example> </refsection> + <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.report-format"><info><title>Setting the Default Report Format</title></info> - <para> By default, PHP_CodeSniffer will use the <emphasis>full</emphasis> report format if no format is supplied on the command line. You can change the default report format by setting the <literal>report_format</literal> configuration option. </para> <example><info><title>Setting the default report format to be the summary report</title></info> - <screen> <userinput> <![CDATA[ @@ -42,13 +37,12 @@ </example> </refsection> + <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.show-warnings"><info><title>Hiding Warnings by Default</title></info> - <para> By default, PHP_CodeSniffer will show both errors and warnings for your code. You can hide warnings for a single script run by using the <literal>-n</literal> command line argument, but you can also enable this by default if you prefer. To hide warnings by default, set the <literal>show_warnings</literal> configuration option to <literal>0</literal>. </para> <example><info><title>Hiding warnings by default</title></info> - <screen> <userinput> <![CDATA[ @@ -64,13 +58,12 @@ </note> </refsection> + <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.tab-width"><info><title>Setting the Default Tab Width</title></info> - <para> By default, PHP_CodeSniffer will not convert tabs to spaces in checked files. Specifying a tab width will make PHP_CodeSniffer replace tabs with spaces. You can force PHP_CodeSniffer to replace tabs with spaces by default by setting the <literal>tab_width</literal> configuration option. </para> <example><info><title>Setting the default tab width to be 4 spaces</title></info> - <screen> <userinput> <![CDATA[ @@ -84,7 +77,6 @@ When the tab width is set by default, the replacement of tabs with spaces can be disabled for a single script run by setting the tab width to zero. </simpara> <example><info><title>Disabling the replacement of tabs with spaces</title></info> - <screen> <userinput> <![CDATA[ @@ -95,22 +87,41 @@ </example> </note> </refsection> - </refsection> - - <refsection xml:id="package.php.php-codesniffer.config-options.squiz"><info><title>Squiz Coding Standard Configuration Options</title></info> - - + <refsection xml:id="package.php.php-codesniffer.config-options.squiz.jslint-path"><info><title>Setting the Path to JSLint</title></info> + <para> + The Squiz coding standard includes a sniff that will check each JavaScript file using <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.jslint.com/">JSLint</link>, a JavaScript program that looks for problems in JavaScript programs. Use the <literal>jslint_path</literal> configuration option to tell the JSLint sniff where to find the tool. + </para> + <example><info><title>Setting the path to JSLint</title></info> + <screen> + <userinput> +<![CDATA[ +$ phpcs --config-set jslint_path /path/to/jslint.js +]]> + </userinput> + </screen> + </example> + <para> + As JSLint is just JavaScript code, you alos need to install <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.mozilla.org/rhino/">Rhino</link> to be able to execute it. Use the <literal>rhino_path</literal> configuration option to tell the JSLint sniff where to find the tool. + </para> + <example><info><title>Setting the path to Rhino</title></info> + <screen> + <userinput> +<![CDATA[ +$ phpcs --config-set rhino_path /path/to/rhino +]]> + </userinput> + </screen> + </example> + </refsection> <refsection xml:id="package.php.php-codesniffer.config-options.squiz.jsl-path"><info><title>Setting the Path to JavaScript Lint</title></info> - <para> The Squiz coding standard includes a sniff that will check each JavaScript file using <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.javascriptlint.com">JavaScript Lint</link>, a tool that checks all your JavaScript source code for common mistakes without actually running the script or opening the web page. Use the <literal>jsl_path</literal> configuration option to tell the JavaScript Lint sniff where to find the tool. </para> <example><info><title>Setting the path to JavaScript Lint</title></info> - <screen> <userinput> <![CDATA[ @@ -120,22 +131,15 @@ </screen> </example> </refsection> - </refsection> - - <refsection xml:id="package.php.php-codesniffer.config-options.zend"><info><title>Zend Coding Standard Configuration Options</title></info> - - <refsection xml:id="package.php.php-codesniffer.config-options.zend.zend-ca-path"><info><title>Setting the Path to the Zend Code Analyzer</title></info> - <para> The Zend coding standard includes a sniff that will check each file using the Zend Code Analyzer, a tool that comes with Zend Studio. Use the <literal>zend_ca_path</literal> configuration option to tell the Zend Code Analyzer sniff where to find the tool. </para> <example><info><title>Setting the path to the Zend Code Analyzer</title></info> - <screen> <userinput> <![CDATA[ @@ -145,7 +149,6 @@ </screen> </example> </refsection> - </refsection> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/faq.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/en/package/php/php-codesniffer/faq.xml diff -u peardoc/en/package/php/php-codesniffer/faq.xml:1.5 peardoc/en/package/php/php-codesniffer/faq.xml:1.6 --- peardoc/en/package/php/php-codesniffer/faq.xml:1.5 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/faq.xml Mon Dec 22 04:00:39 2008 @@ -6,14 +6,12 @@ </refnamediv> <refsection><info><title>Does PHP_CodeSniffer perform any code coverage or unit testing?</title></info> - <para> No. PHP_CodeSniffer is not a tool for testing that your PHP application works correctly. All PHP_CodeSniffer will do is ensure your PHP code meets the standards that you are following. </para> </refsection> <refsection><info><title>My code is fine! Why do I need PHP_CodeSniffer?</title></info> - <para> Maybe you don't, but if you want to ensure you adhere to a set of coding standards, PHP_CodeSniffer is a quick and easy way to do that. PHP_CodeSniffer is a replacement for the more manual task of checking coding standards in code reviews. With PHP_CodeSniffer, you can reserve code reviews for the checking of code correctness. </para> @@ -25,7 +23,6 @@ </refsection> <refsection><info><title>Does PHP_CodeSniffer parse my code to ensure it will execute?</title></info> - <para> No. PHP_CodeSniffer does not actually parse your code, and so cannot accurately tell if your code contains parse errors. PHP_CodeSniffer does know about some parse errors and will warn you if it finds code that it is unable to sniff correctly due to a suspected parse error. However, as there is no actual parsing taking place, PHP_CodeSniffer may return an incorrect number of errors when checking code that does contain parse errors. </para> @@ -45,14 +42,12 @@ </refsection> <refsection><info><title>I don't agree with your coding standards! Can I make PHP_CodeSniffer enforce my own?</title></info> - <para> Yes. At its core, PHP_CodeSniffer is just a framework for enforcing coding standards. We release PHP_CodeSniffer with some sample coding standards to help developers get started on projects where there is no standard defined. If you want to write your own standard, read the <link linkend="package.php.php-codesniffer.coding-standard-tutorial">tutorial on creating coding standards</link>. </para> </refsection> <refsection><info><title>How come PHP_CodeSniffer reported errors, I fixed them, now I get even more?</title></info> - <para> Sometimes, errors mask the existence of other errors, or new errors are created as you fix others. For example, PHP_CodeSniffer might tell you that an inline IF statement needs to be defined with braces. Once you make this change, PHP_CodeSniffer may report that the braces you added are not correctly aligned. </para> @@ -62,9 +57,8 @@ </refsection> <refsection><info><title>Why doesn't PHP_CodeSniffer just make the changes it suggests for me?</title></info> - <para> - As much as we trust PHP_CodeSniffer to check your code for coding standard errors, we don't trust any application to ever change code for us without reviewing it first. Considering we would have to check each change PHP_CodeSniffer made before releasing the source code, why not make the changes manually? + As much as we trust PHP_CodeSniffer to check your code for coding standard errors, we don't trust any application to ever change code for us without reviewing it first. Considering you would have to check each change PHP_CodeSniffer made before releasing the source code, why not make the changes manually? </para> <para> Making the changes manually ensures a couple of positive things happen: @@ -90,10 +84,12 @@ </note> </refsection> - <refsection><info><title>What does PHP_CodeSniffer use to tokenize my PHP code?</title></info> - + <refsection><info><title>What does PHP_CodeSniffer use to tokenize my code?</title></info> <para> - PHP_CodeSniffer uses <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.php.net/tokenizer">PHP's inbuilt tokenizer functions</link> to parse your PHP code. + For PHP files, PHP_CodeSniffer uses <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.php.net/tokenizer">PHP's inbuilt tokenizer functions</link> to parse your code. It then changes that output to include much more data about the file, such as matching function braces to function keywords. + </para> + <para> + For all other file types, PHP_CodeSniffer includes a custom tokenizer that either makes use of PHP's inbuilt tokenizer or emulates it. In both cases, the token array must be checked and changed manually before all the standard PHP_CodeSniffer matching rules are applied, making tokenizing a bit slower for these file types. </para> </refsection> http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/intro.xml?r1=1.6&r2=1.7&diff_format=u Index: peardoc/en/package/php/php-codesniffer/intro.xml diff -u peardoc/en/package/php/php-codesniffer/intro.xml:1.6 peardoc/en/package/php/php-codesniffer/intro.xml:1.7 --- peardoc/en/package/php/php-codesniffer/intro.xml:1.6 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/intro.xml Mon Dec 22 04:00:39 2008 @@ -6,17 +6,17 @@ </refnamediv> <refsection><info><title>Description</title></info> - + <para> - PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP and JavaScript code to detect violations of a defined coding standard. It is an essential development tool that ensures your code remains clean and consistent. It can also help prevent some common semantic errors made by developers. + PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP, JavaScript and CSS files to detect violations of a defined coding standard. It is an essential development tool that ensures your code remains clean and consistent. It can also help prevent some common semantic errors made by developers. </para> <para> - A coding standard, in PHP_CodeSniffer, is a collection of <emphasis>sniff</emphasis> files. Each sniff file checks one part of the coding standard only. Multiple coding standards can be used within PHP_CodeSniffer, so that the one installation can be used across multiple projects. The default coding standard used by PHP_CodeSniffer is the <emphasis>PEAR</emphasis> coding standard. + A coding standard in PHP_CodeSniffer is a collection of <emphasis>sniff</emphasis> files. Each sniff file checks one part of the coding standard only. Multiple coding standards can be used within PHP_CodeSniffer so that the one installation can be used across multiple projects. The default coding standard used by PHP_CodeSniffer is the <emphasis>PEAR</emphasis> coding standard. </para> </refsection> <refsection><info><title>Example</title></info> - + <para> To check a file against the PEAR coding standard, simply specify the file's location. </para> http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/usage.xml?r1=1.13&r2=1.14&diff_format=u Index: peardoc/en/package/php/php-codesniffer/usage.xml diff -u peardoc/en/package/php/php-codesniffer/usage.xml:1.13 peardoc/en/package/php/php-codesniffer/usage.xml:1.14 --- peardoc/en/package/php/php-codesniffer/usage.xml:1.13 Thu Oct 9 15:16:47 2008 +++ peardoc/en/package/php/php-codesniffer/usage.xml Mon Dec 22 04:00:39 2008 @@ -6,20 +6,21 @@ </refnamediv> <refsection xml:id="package.php.php-codesniffer.usage.getting-help"><info><title>Getting Help from the Command Line</title></info> - <para> Running PHP_CodeSniffer with the <literal>-h</literal> or <literal>--help</literal> command line arguments will print a list of commands that PHP_CodeSniffer will respond to. The output of <literal>phpcs -h</literal> is shown below. </para> <para> <screen> <![CDATA[ -Usage: phpcs [-nwlvi] [--report=<report>] [--standard=<standard>] +Usage: phpcs [-nwlsvi] [--report=<report>] [--report-file=<reportfile>] [--config-set key value] [--config-delete key] [--config-show] - [--generator=<generator>] [--extensions=<extensions>] - [--ignore=<patterns>] [--tab-width=<width>] <file> ... + [--standard=<standard>] [--sniffs=<sniffs>] + [--extensions=<extensions>] [--ignore=<patterns>] + [--generator=<generator>] [--tab-width=<width>] <file> ... -n Do not print warnings -w Print both warnings and errors (on by default) -l Local directory only, no recursion + -s Show sniff codes in all reports -v[v][v] Print verbose output -i Show a list of installed coding standards --help Print this help message @@ -29,13 +30,17 @@ (only valid if checking a directory) <patterns> A comma separated list of patterns that are used to ignore directories and files + <sniffs> A comma separated list of sniff codes to limit the check to + (all sniffs must be part of the specified standard) <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 + "csv", "emacs", "source" or "summary" report (the "full" report is printed by default) + <reportfile> Write the report to the specified file path + (report is also written to screen) ]]> </screen> @@ -49,7 +54,6 @@ <refsection xml:id="package.php.php-codesniffer.usage.checking-files-folders"><info><title>Checking Files and Folders</title></info> - <para> 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. </para> @@ -62,7 +66,6 @@ In the example below, the first command tells PHP_CodeSniffer to check the <filename>myfile.inc</filename> file for coding standard errors while the second command tells PHP_CodeSniffer to check all PHP files in the <filename>my_dir</filename> directory. </para> <example><info><title>Checking a single file or folder</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/myfile.inc @@ -74,7 +77,6 @@ You can also specify multiple files and folders to check. The command below tells PHP_CodeSniffer to check the <filename>myfile.inc</filename> file and all files in the <filename>my_dir</filename> directory. </para> <example><info><title>Checking multiple files and folders</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/myfile.inc /path/to/code/my_dir @@ -85,7 +87,6 @@ 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: </para> <example><info><title>Sample PHP_CodeSniffer output</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/myfile.php @@ -109,7 +110,6 @@ If you don't want warnings included in the output, specify the <literal>-n</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer output with no warnings</title></info> - <screen> <![CDATA[ $ phpcs -n /path/to/code/myfile.php @@ -131,12 +131,10 @@ <refsection xml:id="package.php.php-codesniffer.usage.summary-report"><info><title>Printing a Summary Report</title></info> - <para> 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 <literal>--report=summary</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer summary output</title></info> - <screen> <![CDATA[ $ phpcs --report=summary /path/to/code @@ -158,7 +156,6 @@ As with the full report, you can suppress the printing of warnings with the <literal>-n</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer summary output with no warnings</title></info> - <screen> <![CDATA[ $ phpcs -n --report=summary /path/to/code @@ -179,7 +176,6 @@ <refsection xml:id="package.php.php-codesniffer.usage.verbose-output"><info><title>Printing Verbose Output</title></info> - <para> 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. </para> @@ -187,7 +183,6 @@ 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: </para> <example><info><title>Sample PHP_CodeSniffer verbose output</title></info> - <screen> <![CDATA[ $ phpcs /path/to/code/CodeSniffer -v @@ -207,7 +202,6 @@ <refsection xml:id="package.php.php-codesniffer.usage.coding-standard"><info><title>Specifying a Coding Standard</title></info> - <para> 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 <literal>--standard</literal> command line argument. </para> @@ -228,12 +222,10 @@ <refsection xml:id="package.php.php-codesniffer.usage.installed-standards"><info><title>Printing a List of Installed Coding Standards</title></info> - <para> 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 <literal>-i</literal> command line argument. </para> <example><info><title>Generating a list of installed coding standards</title></info> - <screen> <![CDATA[ $ phpcs -i http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-codesniffer/reporting.xml?view=markup&rev=1.1 Index: peardoc/en/package/php/php-codesniffer/reporting.xml +++ peardoc/en/package/php/php-codesniffer/reporting.xml <?xml version="1.0" encoding="utf-8"?> <refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.php.php-codesniffer.reporting"> <refnamediv> <refname>Reporting</refname> <refpurpose>Report types and options</refpurpose> </refnamediv> <refsection><info><title>Printing Full and Summary Reports</title></info> <note> <simpara> See the main <link linkend="package.php.php-codesniffer.usage">usage</link> page for basic usage information about these report types, including example output. </simpara> </note> <para> Both the full and summary reports can additionally show information about the source of errors and warnings. Source codes can be used with the <literal>--sniffs</literal> command line argument to only show messages from a specified list of sources. To include source codes in the report, use the <literal>-s</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer full report with source codes</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> <example><info><title>Sample PHP_CodeSniffer summary report with source codes</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.source-report"><info><title>Printing a Source Report</title></info> <para> 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 <literal>--report=source</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer source output</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> <para> To show source codes instead of friendly names, use the <literal>-s</literal> command line argument. </para> <example><info><title>Sample PHP_CodeSniffer source code output</title></info> <screen> <![CDATA[ $ 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) -------------------------------------------------------------------------------- ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.xml-report"><info><title>Printing an XML Report</title></info> <para> 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 <literal>--report=xml</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer XML output</title></info> <screen> <![CDATA[ $ 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">Missing file doc comment</error> <error line="20" column="43" source="Generic.PHP.LowerCaseConstant">PHP keywords must be lowercase; expected "false" but found "FALSE"</error> <error line="47" column="1" source="PEAR.WhiteSpace.ScopeIndent">Line not indented correctly; expected 4 spaces but found 1</error> <warning line="47" column="20" source="Generic.Formatting.MultipleStatementAlignment">Equals sign not aligned with surrounding assignments</warning> <error line="51" column="4" source="PEAR.Commenting.FunctionComment">Missing function doc comment</error> </file> </phpcs> ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.checkstyle-report"><info><title>Printing a Checkstyle Report</title></info> <para> PHP_CodeSniffer can output an XML report similar to the one produced by <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://checkstyle.sourceforge.net/">Checkstyle</link>, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the <literal>--report=checkstyle</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer Checkstyle output</title></info> <screen> <![CDATA[ $ 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> ]]> </screen> </example> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.csv-report"><info><title>Printing a CSV Report</title></info> <para> 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 <literal>--report=csv</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer CSV output</title></info> <screen> <![CDATA[ $ phpcs --report=csv /path/to/code File,Line,Column,Severity,Message,Source "/path/to/code/myfile.php",2,1,error,"Missing file doc comment",PEAR.Commenting.FileComment "/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\"",Generic.PHP.LowerCaseConstant "/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1",PEAR.WhiteSpace.ScopeIndent "/path/to/code/myfile.php",47,20,warning,"Equals sign not aligned with surrounding assignments",Generic.Formatting.MultipleStatementAlignment "/path/to/code/myfile.php",51,4,error,"Missing function doc comment",PEAR.Commenting.FunctionComment ]]> </screen> </example> <note> <simpara> 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. </simpara> </note> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.emacs-report"><info><title>Printing an Emacs Report</title></info> <para> 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 <literal>--report=emacs</literal> command line argument. The output will look like this: </para> <example><info><title>Sample PHP_CodeSniffer Emacs output</title></info> <screen> <![CDATA[ $ 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 ]]> </screen> </example> <para> To use PHP_CodeSniffer with Emacs, make sure you have installed <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://php-mode.sourceforge.net/">PHP mode for Emacs</link>. Then put the following into your <filename>.emacs</filename> file, changing PHP_CodeSniffer options as required. </para> <example><info><title>Sample .emacs file</title></info> <screen> <![CDATA[ (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) ]]> </screen> </example> <para> Now you can use the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation.html">compile command</link> and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-Mode.html">associated shortcuts</link> to move between error messages within your file. </para> </refsection> <refsection xml:id="package.php.php-codesniffer.reporting.report-file"><info><title>Writing a Report to a File</title></info> <para> 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. </para> <para> To write a copy of a report to a file, use the <literal>--report-file</literal> command line argument. Note that a copy of the report will also be written to the screen. </para> <example><info><title>Writing a report to a file</title></info> <screen> <![CDATA[ $ phpcs --report=xml --report-file=/path/to/file.xml /path/to/code ]]> </screen> </example> </refsection> </refentry>