Until today Jenkins is the leading open-source continuous integration server. There are many other CI servers around, but Jenkins supports building and testing virtually any project. Thanks to its thriving plugin ecosystem. So, why not use it for PHP projects?

The goal of this project is to provide a standard template for Jenkins jobs for PHP projects. It is heavily inspired by Sebastian Bergmann’s “Jenkins PHP Template”, but tries to go one step further.

Why is Continuous Integration for web projects so important? The answer is that web applications are changed constantly and quickly. Environment parameters like the size or the behaviour of the user base, is constantly changing. What is sufficient today can be insufficient tomorrow. Monitoring and continuous improving of the internal quality when developing and maintaining a software is crucial, especially in a web environment.

In this project I’m going to guide you through the installation and configuration process. Simply follow these steps to get started:

1. Prerequisites
2. Install recommended Jenkins plugins
3. Setup an automated PHP build using Apache Ant
4. Create a Jenkins job for your PHP project

Prerequisites

You should be able to install the needed tools on your computer. On my MacBook I’m using the helpful Homebrew which makes installation of applications and command line tools very easy.

Jenkins

The installation of Jenkins is straight forward. After finishing the installation process you can access Jenkin’s web backend by typing http://localhost:8080/ into the address bar of your web browser.

Apache Ant

This article depends on a previous article Automating build process of a PHP Application with Apache Ant. Before you can walk through this article you must have read the depending article.

A simple workflow

A simplified Continuous Integration workflow based on Jenkins CI follows these steps.

1. The Continuous Integration Server like Jenkins CI starts the build process of Apache Ant. This process is invoked by a commit to the Git repo for example.
2. Apache Ant first downloads the Composer PHP-Archive and starts the install process of Composer.
3. Composer installs all PHP-Libraries that are listed in the config file like PHPUnit, PHPCS, Pdepend or PhpDox.
4. Apache Ant loops through the PHP-Tools and executes them, writes different Logfiles and prints out messages to the CLI.
5. The Continuous Integration Server processes the different logfiles, prints them out in a human readable format and creates some graphics. Furthermore it informs project members by e-mail about the build status.

Install recommended Jenkins plugins

You should understand the following list of plugins as a recommendation or starting point for your Continuous Integration project. It is not necessary to install all of the following plugins. So, install the following plugins or only a part of:

• Checkstyle for processing logfiles in Checkstyle format, that are generated by PHP_CodeSniffer.
• Clover PHP for processing Clover XML logfiles, that are generated by PHPUNit.
• Crap4J for processing Crap4J XML logfiles, that are generated by PHPUnit.
• DRY for processing logfiles in PMD-CPD format, that are generated by PHPCPD.
• HTML Publisher for publishing documentation generated by phpBox.
• JDepend for processing logfiles in JDepend format, that are generated by PHP_Depend.
• Plot for processing CSV outputs generated by PHPLOC.
• PMD for processing logfiles in PMD format, that are generated by PHPMD.
• Violations for processing various logfiles.
• Warnings for processing warnings in the console log, that are generated by the PHP compiler.
• xUnit for processing JUnit XML logfiles that are generated by PHPUnit.
• Phing as a possible alternative to Apaches Ant.

You can install the above plugins by using the web frontend or Jenkins CLI client.

Setup a PHP project with an automated build using Apache Ant

Use the following commands to setup an example PHP project that supports an automated build process using Apache Ant.

$ git clone https://github.com/code-smell/php-automate-build-ant.git my-project
$ cd my-project
$ ant full-build

The full-build target downloads Composer as a PHP Archive, installs all dependencies, performs static analysis, runs Unittests, and generates project documentation.

You should see a BUILD SUCCESSFUL message in the terminal if everything is okay.

Create a Jenkins job for your PHP project

Using the Job Template

1. Fetch the jenkins-cli.jar from your jenkins server:

wget http://localhost:8080/jnlpJars/jenkins-cli.jar

2. Download and install the PHP Jenkins job template:

curl -L https://raw.githubusercontent.com/code-smell/php-jenkins-job-template/master/config.xml | \
java -jar jenkins-cli.jar -s http://localhost:8080 create-job php-job-template

or add the template manually:

cd $JENKINS_HOME/jobs
mkdir php-job-template
cd php-job-template
wget https://raw.github.com/code-smell/php-jenkins-job-template/master/config.xml
cd ..
chown -R jenkins:jenkins php-job-template/

3. Reload Jenkins’ configuration, for instance using the Jenkins CLI:

java -jar jenkins-cli.jar -s http://localhost:8080 reload-configuration

4. Click on “New Job”.

5. Enter a “Job name”.

6. Select “Copy existing job” and enter “php-job-template” into the “Copy from” field.

7. Click “OK”.

8. Uncheck the “Disable Build” option.

9. Fill in your “Source Code Management” information.

10. Configure a “Build Trigger”, for instance “Poll SCM”.

11. Click “Save”.

Troubleshooting

No “Copy existing job” option / “php-job-template” project does not show up

Jenkins cannot find the php-job-template job. Make sure you cloned to the right directory. Check the permissions to make sure the Jenkins user has read and write access to the directory. Restart Jenkins.

General Setup Issues

Check the management panel http://localhost:8080/manage and the Jenkins log for messages.

HTML Code is shown on the project status page

The default for rendering HTML has been changed in Jenkins 1.553. To correctly display the charts generated by PHP_Depend, you need to enable security on http://localhost/configureSecurity/ and change the Markup Formatter to Raw HTML.