PHPCheckstyle Code

122 lines (82 with data), 5.4 kB

#summary PHPCheckstyle documentation
#labels Featured

<wiki:toc max_depth="2" />

= Overview =

PHPCheckstyle is an open-source tool that helps PHP programmers adhere to certain coding conventions. The tools checks the input PHP source code and reports any deviations from the coding convention.

The tool uses the [http://pear.php.net/manual/en/standards.php PEAR Coding Standards] as the default coding convention. But it allows you to configure it to suit your coding standards. The configuration file is a simple to understand xml file explained in the Configuration section.

= Requirements =
 * PHP 5.0 or newer.
 * Web browser to view the checkstyle report (for html reports)
 * That’s all

= Installation =

* Unzip the distribution.
{{{
unzip phpcheckstyle.zip
}}}

= Configuration =

The configuration file used by default is config/default.xml.

The user can customize this to suit it to specific coding convention by creating a new configuration file and commenting/uncommenting some tests.

To change the configuration file used, use the --config flag of the command line.

*Note* : The php.ini used in CLI (Command Line Interface) may be different than the php.ini used by your web server. If the "short_open_tag" param is "Off" in the php.ini, the PHP tokenizer will not correctly return the tokens inside short tags.


= Running PHPCheckstyle =
 * Change directory to the PHPCheckstyle installation directory.
{{{
cd phpcheckstyle
}}}
 * Execute the run.php script providing the --src option.
{{{
php run.php --src "php source directory/file"
}}}

=== Command line Options ===

Execute the run.php script without any options or with the --help option to see the supported command line options.
{{{
 $> php run.php --help

 Usage: php/run.php <options>

    Options:
       --src          Root of the source directory tree or a file.
       --exclude      [Optional] A directory or file that needs to be excluded.
       --format       [Optional] Output format (html/text/console). Defaults to 'html'.
       --outdir       [Optional] Report Directory. Defaults to './style-report'.
       --config       [Optional] The name of the config file.
       --debug        [Optional] Add some debug logs (warning, very verbose).
       --linecount    [Optional] Generate a report on the number of lines of code (JavaNCSS format)
       --help         Display this usage information.  
}}}

  * --src: Specifies the php source file. Or a directory under which the php source files reside. If a directory is specified then all the php files within that directory will be processed (unless the a file or subdirectory is in the --exclude list)
  * --exclude: Excludes the specified file or directory from processing. Specify multiple times for more than one file/directory
  * --outdir: The directory where the checkstyle report is to be stored. The default is ./style-report.
  * --format: Can be "html", "text", "xml" and/or "console". Default is "html". The report is generated in the file outdir/index.html in case of "html" format or outdir/style-report.txt in case of "text" format. The "console" mode can be used to interact with tools that analyse the output of the console like the DLTK tools of Eclipse. The xml output can be used with tools like the Hudson/Jenkins violations plugin. If multiple formats are selected, they should be separated with a comma.
  * --config: Allow to specify the name of the configuration file used. The config file must be placed in the "config" directory.
  * --debug: Generates some debug information about the code analysed (it shows the tokens found, this is very verbose).
  * --linecount: Generates a new XML file in the JavaNCSS format that will contain informations about the number of classes, functions, lines of code and lines of comment of the analysed project.

= Using PHPCheckstyle with ANT =

See [UsingWithANT Using PHPCheckstyle with ANT].

= Using PHPCheckstyle with Eclipse =

See [UsingWithEclipse Using PHPCheckstyle with Eclipse].

= Using PHPCheckstyle with Netbeans =

See [UsingWithNetBeans Using PHPCheckstyle with NetBeans].

= Using PHPCheckstyle with Hudson / Jenkins =

See [UsingWithJenkins Using PHPCheckstyle with Hudson / Jenkins].

= Using PHPCheckstyle as a web interface =

If PHPCheckstyle is located on the same web server as the code that you want to check, you can call directly the "index.php" page and use your browser to launch the analysis. 

= Counting the lines of code of a project =

By adding the "--linecount" option to the command line, PHPCheckstyle will generate an XML file compatible with the [http://kclee.de/clemens/java/javancss/ JavaNCSS] format

This could be used with the [http://wiki.hudson-ci.org/pages/viewpage.action?pageId=36603031 JavaNCSS plugin] of Hudson.

= Suppressing Warnings =

Warnings can be removed with the help of annotations on a function level or a class level. 

To remove a warning add the annotation "@SuppressWarnings warningName" in the PHPDoc where warningName is the identifier of the check rule. 

The identifier of the rule is displayed as a tooltip in the generated HTML report.

{{{
/**
 * This is a data objet without getter or setter.
 *
 * @package classes
 * @SuppressWarnings checkUnusedVariables
 */
class MyDataObject {

  /**
   * This property is not used in the class and would have raised a warning.
   */
   var $myProperty;

}

}}}