== Overview ==
Spike 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.
== Installing Spike PHPCheckstyle ==
Make sure the [http://developer.spikesource.com/wiki/index.php?title=Projects:phpcheckstyleRequirements Requirements] are matched (PHP XSL extension needs to be enabled).
Unzip the distribution.
<pre>unzip phpcheckstyle.zip</pre>
This will create a directory called phpcheckstyle and expand all files in it.
== Running Spike PHPCheckstyle ==
* Change directory to the Spike PHPCheckstyle installation directory.
<pre>cd phpcheckstyle</pre>
* Execute the run.php script providing the --src option.
<pre>php run.php --src "php source directory/file"</pre>
=== Command line options ===
Execute the run.php script without any options or with the --help option to see the supported command line options.
<pre>
$> 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.
</pre>
* --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: Either "html", "text" 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.
* --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 [http://www.kclee.de/clemens/java/javancss/ JavaNCSS] format that will contain informations about the number of classes, functions, lines of code and lines of comment of the analysed project.
== 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.
See [http://developer.spikesource.com/wiki/index.php?title=Projects:phpcheckstyleTests Tests] for a detailled description of the available tests.
== Using PHPCheckstyle with Eclipse ==
Eclipse is already able to do some checks and to reformat your code (CTRL + SHIFT 9+ F) with [www.eclipse.org/pdt/ PDT].
It is also possible to add some extenal tools like PHP_CodeSniffer or PHP_Checkstyle to verify the code you're editing.
* First, install the Eclispe PHP Tool Integration (see http://www.phpsrc.org/wiki/)
Eclipse Update URL : http://www.phpsrc.org/eclipse/pti/
* Get last version of PHP Checkstyle.
* In Eclipse, configure a new validator :
** Preferences->Dynamic Languages->Validators
** Click "Add..."
** Select the "External PHP Script" type
** Set the Path to the PHP Checkstyle "run.php" file.
** Configure the PHP Executable to match your environment.
* Add some arguments to the executable
<pre>--src %f --config "default.cfg.xml" --format console</pre>
* Add some pattern rules to read the result:
** %f INFO Line:%n - %m Warning
** %f WARNING Line:%n - %m Warning
** %f ERROR Line:%n - %m Error
And it should be OK, on your PHP Editor, right click, select "DLTK Validators" and the script should run.
== Using PHPCheckstyle with Hudson ==
The XML generated by PHP_Checkstyle is compatible with the original [http://checkstyle.sourceforge.net/ Checkstyle] XML format.
The [http://wiki.hudson-ci.org/display/HUDSON/Violations Violation plugin] of [http://hudson-ci.org/ Hudson] is capable of reading this file and displaying and historising the results.
See the [http://developer.spikesource.com/forums/viewtopic.php?t=955 forum] for an example of ANT task.
== 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 [http://hudson-ci.org/ Hudson]
== Links ==
* [http://pear.php.net/package/PHP_CodeSniffer/ PHP_CodeSniffer] is a very complete PHP code analysis tool.
* [http://phpmd.org/about.html PHPMD] Is the PHP equivalent of PMD
* [http://strategoxt.org/PHP/PhpSat#Features PHP_sat] is another code analysis tool for PHP.
* [http://pdepend.org/ PDepend] is another static analysis tool and can generate some metrics about inter package dependencies.
* [http://www.phpunit.de/ PHPUnit] is the PHP tool for unit testing. It can also generate some PMD-like informations about the code (but it must be linked to a test).
* [http://www.softwarehood.com/Codenizer Codenizer] is yet another code analysis tool (not open-source)
* [http://checkstyle.sourceforge.net/ Checkstyle] is a JAVA code analysis tool.
* [http://pmd.sourceforge.net PMD] is another JAVA code analysis tool.
* [http://findbugs.sourceforge.net/ Findbugs] is another JAVA code analysis tool.
* [http://www.kclee.de/clemens/java/javancss/ JavaNCSS] a JAVA tool for counting the lines of code in a project.
* [http://phpundercontrol.org/about.html phpUnderControl] is a continuous integration tool designed for PHP (based on CruiseControl, PHPUnit, PHP_CodeSniffer and PHPDepend).
* [http://hudson-ci.org/ Hudson] is a continuous integration tool that can benefit from a lot of available plugins.
* [http://developer.spikesource.com/projects/phpcoverage PHPCoverage] is a test coverage tool for PHPUnit.
* [http://en.sourceforge.jp/projects/pdt-tools/] Is a set of plugins for Eclipse PDT with automatic format options
