Manuel Pichler

This is just a small bugfix release of PHPMD. It introduces a small new feature that enables PHPMD's command line tool to handle multiple input files. This feature was required for some upcoming external features and extensions. Since version 0.2.1 you can call the command line tool of PHPMD with multiple input files and/or directories, separated by comma.

mapi@arwen ~ $ phpmd phpmd,systemDaemon text unusedcode

You can get the latest PHPMD version from its PEAR channel: pear.phpmd.org

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear channel-discover pear.phpmd.org
mapi@arwen ~ $ pear install --alldeps phpmd/PHP_PMD-alpha

Today I have released version 0.2.0 of the PHP Mess Detector or short PHPMD. PHPMD is a simple, customizable and user friendly frontend application for PHP_Depend. It takes the raw metrics measured by PHP_Depend, compares them with appropriate thresholds and generates a report that lists those software artifacts with potential problems. Such a report can be taken as a basis for human code audits or you can use it as input for an automated build/reporting tool.

Most concepts behind PHPMD are based on those of the well known Java Tool PMD. It uses so called rule set files to organize different sets of rules. There are two purposes that are accomplished by these xml files. The first is to create custom sets of rules which fulfills the projects requirements. The second purpose is the configuration of each rule with thresholds, warning messages and other things. The format of these files is totally borrowed from PMD, so that the reuse existing rule sets in multi language environments should be easy. At the moment PHPMD has two build-in rule sets. One that detects software artifacts with high code size, and the second one detects unused code in your software.

Now lets start with a small How to use it. PHPMD can be called from the command line by typing phpmd, which prints a general help text.

mapi@arwen ~ $ phpmd 
Mandatory arguments:
1) A php source code filename or directory
2) A report format
3) A ruleset filename or a comma-separated string of ...

Optional arguments that may be put after the mandato...
--minimumpriority: rule priority threshold; rules with ...
--reportfile: send report output to a file; default to ...
--extensions: comma-separated string of valid source ...
--ignore: comma-separated string of patterns that are ...

Now let's call PHPMD on its own source, with a simple text report on STDOUT and the codesize ruleset:

mapi@arwen ~ $ phpmd ~/phpmd/source text codesize

/home/mapi/phpmd/source/PHP/PMD/RuleSetFactory.php:66 \
  This class has too many methods, consider refactoring it.
/home/mapi/phpmd/source/PHP/PMD/RuleSetFactory.php:267 \
  The method _parseSingleRuleNode() has a Cyclomatic \
  Complexity of 11.
/home/mapi/phpmd/source/PHP/PMD/RuleSetFactory.php:326 \
  The method _parseRuleReferenceNode() has a Cyclomatic \
  Complexity of 10.

The --reportfile option can be used, to redirect the report output into a file. So let us repeat the previous example that writes the report into a file, additionally uses the unusedcode rule and changes the format from text to xml.

mapi@arwen ~ $ phpmd ~/phpmd/source xml codesize,unusedcode \
  --reportfile ~/pmd.xml
mapi@arwen ~ $ cat ~/pmd.xml 
<?xml version="1.0" encoding="UTF-8" ?>
<pmd version="@package_version@" timestamp="...">
  <file name=".../source/PHP/PMD/RuleSetFactory.php">
    <violation beginline="66" endline="417" rule="TooManyMet ...>
      This class has too many methods, consider refactoring it.
    </violation>
    <violation beginline="267" endline="315" rule="Cyclomati ...>
      Method _parseSingleRule() has a Cyclomatic Complexity of 11.
    </violation>
    <violation beginline="326" endline="367" rule="Cyclomati ...>
      Method _parseRuleReference() has a Cyclomatic Complexity of 10.
    </violation>
  </file>
</pmd>

This xml file is compatible with those files generated by PMD and PHPUnit's deprecated --log-pmd option. So that it should be no problem to use this files in existing environments like Hudson, CruiseControl or Sonar.

Currently PHPMD supports the following three different report formats: Text, HTML and XML. And it has the build-in rule sets: codesize and unusedcode.

You can get the latest PHPMD version from its PEAR channel: pear.phpmd.org

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear channel-discover pear.phpmd.org
mapi@arwen ~ $ pear install --alldeps phpmd/PHP_PMD-alpha

Today I released PHP_Depend 0.9.8, which contains many bug fixes and improvements. This release will be the base version for a new tool called PHPMD. PHPMD is a frontend that reports critical and suspect software artifacts in a project, based on the metrics measured with PHP_Depend. It aims to be a PHP equivalent to the well known java tool PMD.

• Closed #93: Implement an assignment expression, Implemented in svn revision #992.
• Fixed #94: Parser throws exception for closures that return by reference, fixed in svn revision #962.
• Fixed #98: Functions with an invalid signature result in an inconsistent object graph, fixed in svn revision #986.
• Fixed #102: Namespace keyword in type-hint is broken, fixed in svn revision #1010.
• Fixed #103: The parser does not handle all strings as parameter default value correct, fixed in svn revision #1009.

You can get the latest PHP_Depend version from its PEAR channel: pear.pdepend.org

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear install pdepend/PHP_Depend-beta

This is the first release of the phpUnderControl tool. This tool aims to take the first steps with CruiseControl and PHP as easy as possible. phpUnderControl integrates three of the best PHP development tools into CruiseControl, combined with an easy setup routine and a small example project. With the provided XSL-Stylesheets the generated output of PHPUnit, PHP_CodeSniffer and phpDocumentor can be visualized in CruiseControl, as you can see in the following screenshot.

PHP coding violations visualized in CruiseControl

Getting started

Now let's take a look how to start with CruiseControl and phpUnderControl. The first things you need is a Java environment and a working installation of CruiseControl. I assume that Java is already installed and so I will not cover this topic here, but I suggest to use an original Java version from SUN instead of some versions bundled with linux distributions, because in combination with compiz or beryl the metrics view can be broken.

Getting a working CruiseControl installation is a simple task. Just download one of the provided zip archives, unpack the contents and start the application. Because this initial release of phpUnderControl is only tested with CruiseControl 2.7, I suggest to use this version for the moment. You can download this version, if you click the following link:

cruisecontrol-bin-2.7.zip

When the download has finished, just unzip the archive.

unzip cruisecontrol-bin-2.7.zip -d /opt/

For a detailed installation description how to install CruiseControl and how to configure it with PHPUnit I recommend an excellent article by Sebastian Nohn and the Continuous Integration chapter from the PHPUnit Pocket Guide written by Sebastian Bergmann.

Now, that you have a working CruiseControl, download the phpUnderControl tool from the following url and unpack the archive:

Small bugfix release, I left some system() calls in the source code.
phpUnderControl-0.1.1.tar.gz

phpUnderControl-0.1.0.tar.gz

Now, you need to change to the phpUnderControl/bin directory and execute the following command to install the required files. All files that the command line tool modifies, are backed up with the file extension .orig.

[mapi@frodo bin]$ ./phpuc.php install /opt/cruisecontrol-bin-2.7

Modifying CruiseControl files.
  File "main.jsp" modified.
  File "metrics.jsp" modified.
  File "xsl/buildresults.xsl" modified.

Installing new CruiseControl files.
  File "phpcs.jsp" installed.
  File "phpunit-pmd.jsp" installed.
  File "xsl/phpcs.xsl" installed.
  File "xsl/phpcs-details.xsl" installed.
  File "xsl/phpdoc.xsl" installed.
  File "xsl/phphelper.xsl" installed.
  File "xsl/phpunit-pmd.xsl" installed.
  File "xsl/phpunit-pmd-details.xsl" installed.

Modifying CruiseControl stylesheet.
  Creating backup of "css/cruisecontrol.css" as "css/cruisecontrol.css.orig".

All you need now is an application with that CruiseControl can work. phpUnderControl comes with a little example application which can be installed with the following command. This example doesn't require any version control system installation. Instead it uses a special tag, that CruiseControl provides.

[mapi@frodo bin]$ ./phpuc.php example -t ant /opt/cruisecontrol-bin-2.7
Creating required project directories.
  1. Creating CruiseControl project dir "projects/php-under-control".
  2. Creating Project input dir "php-under-control/source".
  3. Creating Project source dir "php-under-control/source/src".
  4. Creating Project test dir "php-under-control/source/tests".
  5. Creating Project build dir "php-under-control/build".
  6. Creating Project log dir "php-under-control/build/logs"
  7. Creating API documentation dir "/tmp/php-under-control/api"
  8. Creating Coverage dir "/tmp/php-under-control/coverage"

Creating example files.
  Creating file "php-under-control/source/src/Math.php".
  Creating file "php-under-control/source/tests/MathTest.php".

Creating project build file "php-under-control/build.xml".

Preparing CruiseControl "/opt/cruisecontrol-bin-2.7/config.xml.
  1. Loading "config.xml" data.
  2. Backup original "config.xml" as "config.xml.orig".
  3. Creating new project configuration.

Now change to the /opt/cruisecontrol-bin-2.7 directory and execute the cruisecontrol.sh or cruisecontrol.bat script to start CruiseControl. If you open your browser with this url http://127.0.0.1:8080/buildresults/php-under-control you will see something similar to the next screenshot.

CruiseControl Buildresult view after installation

PHPUnit features integrated

As mentioned in a previous post Sebastian Bergmann integrated support for Software Metrics and PMD in the PHPUnit 3.2 branch. Because he has used the original PMD format, the generated output was usable for CruiseControl without any modifications. Additionaly he integrated a third party contribution for Copy & Paste Detection that makes finding duplicate code fragments much easier. To show the results of this new report type the phpUnderControl tool provides modified versions of the original files pmd.xsl, pmd-details.xsl and metrics.jsp that can visualize the new records.

Copy & Paste Detection

PHP_CodeSniffer integration

The PEAR package PHP_CodeSniffer makes us PHP developers a present. With this handy tool coding guildline checks have become a really simple task. As a positive reaction on an other article Greg Sherwood, the lead developer of PHP_CodeSniffer, added support for the Checkstyle format to this package. Cool :-), with the upcoming 1.0.0RC3 release of PHP_CodeSniffer this package will work together with CruiseControl without any changes. The following screenshot shows the PHP_CodeSniffer result for the phpUnderControl example. Please note, all these errors are provoked and not the result of bad coding

PHP_CodeSniffer in CruiseControl

PLEASE NOTE: The current version 1.0.0RC2 has a small bug in the checkstyle output that causes CruiseControl to fail with the Checkstyle report. I hope this will be fixed in the RC3 release, but if you cannot wait just change line 720 in <pear-install>/PHP/CodeSniffer.php from

echo ' line="'.$line.' "column="'.$column.'"';

to

echo ' line="'.$line.'" column="'.$column.'"';

or you apply the following patch to <pear-install>/PHP/CodeSniffer.php

Index: CodeSniffer.php
===================================================================
RCS file: /repository/pear/PHP_CodeSniffer/CodeSniffer.php,v
retrieving revision 1.55
diff -r1.55 CodeSniffer.php
720c720
<                         echo ' line="'.$line.' "column="'.$column.'"';
---
>                         echo ' line="'.$line.'" column="'.$column.'"';

or you modify the build.xml file and use the XSL-Stylesheet from my previous post.

phpDocumentor integration

During the last user group meeting, while all others were hacking on some stuff. I thought this small javadoc legend in the "Coding violations" view must be fillable with the results of the standard PHP documentation tool phpDocumentor. The current integration is based on text matching onto the command line output of the phpdoc script which is not a perfect solution. For a future release of phpUnderControl there will be a custom implementation of the output converter that will process the documentation errors and warnings.

PHPDoc integration.

Finally

I hope this post and the phpUnderControl tool helps someone and was interesting for some of the readers. The current version is only tested under linux which means that I cannot say anything about windows, so I would be delighted if someone provides windows phpuc.bat or phpuc.cmd file.