Manuel Pichler

Today I have released the second beta version of phpUnderControl. Beside several minor tweaks and bug fixes, this release contains one additional feature I was asked for during the IPC in Berlin. This feature allows you to specify a maximum number of log entries that will be shown in the generated metric charts. This can be very useful once you have a project with a great amount of builds and the chart rendering gets slower and slower.

This feature adds a new option --max-number to phpUnderControl's chart command. To rebuild all your charts you can call phpUnderControl's shell script with the following command:

  mapi@arwen ~ $ phpuc --force-update --max-number 42 \
                 /opt/cruisecontrol/logs/phpUnderControl \
                 /opt/cruisecontrol/logs/phpUnderControl

You can get the latest release of phpUnderControl through its pear channel:

  mapi@arwen ~ $ pear upgrade --alldeps phpuc/phpUnderControl-0.6.0beta2
  Starting to download phpUnderControl-0.6.0beta2.tgz (546,314 bytes)
  ...................................................................
  .............................done: 546,314 bytes

or you can get the latest development version on github.

Just now I found in Felix's blog this excellent phpUnderControl tutorial that comes with useful tips and helping scripts. Because I think it is a really good source to get started with phpUnderControl I will link it here.

• Bug fix: CC is compatible with Java 1.5, but the phpUnderControl 0.4.6 sources were compiled against Java 1.6.

Visit phpUnderControl's download page for release packages.

• Fixed #621: phpUnderControl dashboard is broken with CruiseControl 2.8 - [4085]
• Closed #609: Use artifacts directory for artifacts - [4118]
• Closed #611: opera: code coverage not visible - [4119]
• Closed #622: phpUnderControl needs a custom error page - [4116]

There was a documentation error in the previously presented ant build file for the new merge-phpunit command of phpUnderControl. The @failonerror-attribute of the <exec />-tag in the merge target was set to false, which results in not failed CruiseControl builds To fix this behaviour, you must modify the merge target in your build.xml, so that it looks similar to the following example.

Beside this documentation error, there was a bug in version 0.4.3 related to the same topic, which is fixed now. So please make sure you have the latest version (at least 0.4.4) installed.

I recently released a bugfix version of phpUnderControl. Beside some minor view errors like the odd/even rows problem, the 0.4.4 release of phpUnderControl fixes a bug in the new merged phpunit logs feature, which doesn't cause CruiseControl to fail for such builds.

I currently released a new version of phpUnderControl. Beside some minor fixes this release comes with a new feature to aggregate test results of multiple PHPUnit runs.

Use the new cli command merge-phpunit of phpUnderControl to merge multiple log files produced with PHPUnit, as shown in the following example build file for ant.

phpUnderControl merged phpunit log view

Yesterday kore asked me about a strange behavior of phpUnderControl. The last arbit build done by phpUnderControl has failed, but when we looked over the different result pages everything looks fine.

phpUnderControl overview page of arbit

Strange! What has happened?

After an analysis session of the 6MB XML log file I detected the following self explaining entry. The PHPUnit tests for arbit had completely failed.

Ok, the test run failed, but why did phpUnderControl say: All Tests passed?

The answer is really simple. Due to the fact that phpunit died, it didn't generate any log file and previous log files still reside in build/logs. Because CruiseControl cannot know anything about these outdated build artifacts, it still publishes them as result for last build.

At this moment I realized that I have never mentioned a clean-target for the ant build.xml file, neither in the example file nor in a blog post or the FAQ. So now its time to catch up on this topic.

You should add an additional target to your ant build.xml file, that removes all log files and build artifacts of previous builds, before the main build cycle starts.

That's it. Now you will get the expected(not really) result: No Tests Run - This project doesn't have any tests.

A few minutes ago I have released the latest phpUnderControl 0.4.0 version. In addition to many minor fixes and improvements this version comes with three utility commands, that should simplify some common tasks.

1) Project delete

The project delete command provides a simple way to delete a complete project with all its contents, including logs, artifacts and sources, from your CruiseControl installation.

[mapi@arwen~]$ phpuc delete --project-name connectfour /opt/cruisecontrol

2) Project clean

I do not really like this feature, because I really dislike the idea to delete old builds and artifacts, but I must admit that I have mounted a 100 GB partition as artifacts directory. Due to the fact that this feature was requested by many phpUnderControl users, it is implemented in phpUnderControl 0.4.0.

This command allows you to delete old logs and artifacts except a configurable number of the latests builds. The following command will remove all build results for the php-under-control except the last 20 builds.

[mapi@arwen~]$ phpuc clean --project-name php-under-control \
                           --keep-builds 20 /opt/cruisecontrol

3) Project create

The project create command provides a cli wizard to set up a new CruiseControl project. The following command will create a new project for the PHPUnit BankAccount sample, checkout the latest svn version, create the required directories and finally prepare the ant build.xml and the CruiseControl config.xml. If you don't like XML or you have multiple projects, that share a common source/project layout, this command could be useful for you.

[mapi@arwen~]$ phpuc project --version-control svn \
                             --version-control-url svn://svn.phpunit.de/.. \
                             --project-name BankAccount2 \
                             --source-dir . \
                             --test-case BankAccountTest \
                             --test-dir . \
                             --test-file BankAccountTest.php \
                             --schedule-interval 20 \
                             /opt/cruisecontrol

But I would always recommend to use the example build.xml and config.xml to set up a new project. Both files are completely documented and contain links to the original CruiseControl configuration reference.

I will do my best to complete the missing documentation for the CruiseControl config.xml file and the new cli commands. Any help is welcome.

Here is a small code snippet that can be used to integrate php's internal lint syntax check into your build process. The ant task apply behaves like the exec task, but it accepts a nested fileset element. This allows to process a set of input files thru a single command.

This can also be used as an addition in your phpunit target or any other command which executes code during the build-process, when the command would quit due to a syntax error.

Due to the fact that every software is individual and in this context the used tools differ from build-process to build-process phpUnderControl 0.3.6 introduced a new feature that allows to customize the main menu bar. It is a simple placeholder based preprocessor. It extracts custom tabs from an existing phpUnderControl installation and takes them into newer version during the update process.

At the moment only the main.jsp file supports this new preprocessor between each of the predefined tabs. Each phpUnderControl placeholder has the following format <%-- phpUnderControl ([0-9]+) --%> where ([0-9]+) represents a unique number. The following example shows a section from the main.jsp file as it is shipped with phpUnderControl 0.3.6.

Now I would like to add two more documentation types to my build result. The agile Testdox documentation, generated by PHPUnit and the end user documentation generated from docbook xml files in the source repository.

I simply translated the placeholder number 5 into an opening %<-- begin phpUnderControl 5 --%> and a closing <%-- end phpUnderControl 5 --%> placeholder and put my custom tabs between this two comment. And this is what it looks like now.

Customized phpUnderControl tab-panel

And the best thing is that you do not need to worry about future updates.

Except minor enhancements and bugfixes the latest phpUnderControl version comes with two new features.

Customizable tab-panel

This version allows you to define additional tabs in the main tab-panel. These can be used for further artifacts. Future phpUnderControl updates care about custom tabs and keep them in the new version.

Test execution time

This version has a new chart, which visualizes the trend of the unit test execution time.

Test execution time metric

Yesterday I have released the latest phpUnderControl 0.3.5 version. In addition to many minor improvements this version brings two new features. A new index page, inspired by the dashboard of the continuous integration tool hudson

phpUnderControl dashboard

and a custom PhpDocumentor template which has its roots in the eZ Components api documentation.

new phpdoc template.

Except these changes phpUnderControl comes with a lot of minor visual changes, mostly done by kore. Anymore I would like to thank tobias for his work on saturday evening, to get the phpunit.de pear channel to work

Yesterday I released version 0.3.(0|1|2) of phpUnderControl. Except bugfixes and enhancements the major change in this new version of phpUnderControl is an ezcGraph replacement of the original cewolf metrics view. For the excellent appearance of the generated graphics I would like to thank kore, who supported me actively with his deep knowledge of the ezcGraph component. Beside the better appearance, the new graph implementation has another advantage, it performs much better than the original cewolf implementation, because cewolf generates graphics in real time, while the new ezcGraph solution generates static graphics during the build process.

phpUnderControl 0.3.2 Metrics

To integrate the graph generator into your build process, you must alter the <publishers /> elements in the config.xml file. Simply add a CruiseControl execute-publisher that calls the phpUnderControl cli tool with the graph command, as shown in the following example.

The phpUnderControl graph command expects at least the project log directory as argument, it is the directory where CruiseControl stores the merged xml log files. In this default mode phpUnderControl will generate the metric charts for each build into logs/<project-name>/<build-timestamp>/graph directories. If you use a different CruiseControl setup where artifacts are not stored in the logs/ directory you can call the graph command with a second argument that specifies the output directory, for example:

[mapi@arwen /opt/cruisecontrol]$ phpuc graph logs/phpUnderControl \
                                             artifacts/phpUnderControl

Finally I say thanks to Sebastian, because he integrates a new css file for the coverage reports into PHPUnit, that produces a harmonious overall picture between phpUnderControl and the coverage-report. This stylesheet is yet another contribution by kore.

PHPUnit Coverage report

All phpUnderControl versions are available thru the phpunit.de pear channel, just type:

[mapi@arwen ~]$ pear channel-discover pear.phpunit.de
[mapi@arwen ~]$ pear install --alldeps phpunit/phpUnderControl-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.