Elephpant in the pipeline — CI

Luis Ferro
Jul 30, 2017 · 3 min read

The migration of a PHP project from Jenkins 1 to a brand new Jenkins 2 pipeline setup.

A successful elephpant in a pipeline

This is the journey of setting up Jenkins to run all the tasks related with automated testing, continuous integration and the gathering of code quality statistics for improved development practices.

“If you can’t measure it, you can’t improve it.” — Peter Drucker (1)

I will not go into the details on how to setup Jenkins 2, because the only thing needed is to go to https://jenkins.io (2) and install it (I still remember, with dread, having to setup Jenkins with Apache Tomcat as it was the only option available at the time).

Nevertheless, I digress.


To setup Jenkins 2 to work with PHP projects, just go to the excelent http://jenkins-php.org (3) site and follow the instructions to install and setup all the Jenkins plugins and PHP Tools (instalation step).

The Ant script (automation step) isn’t required (you still can set it up, but in my project I decided not to — I wanted things as simple as possible).

The configuration step is mostly straightforward. The only thing that you may want to change are the target folders.

In my case, this was simply to start moving to a file structure that is Symfony 4 (4) compatible.

The only change was related with PHPDox (5), more precisely the export / build configuration:

The relevant part is the <build/> tag where one needs to add the templates location

I also had to manually download the phpdox templates since they were not present (on newer versions of PHPDox this is probably handled automatically).

After all the tools are working with the appropriate configuration files and parameters (by using the CLI directly, or using the Ant build script), you can add them in the Jenkinsfile (6):

Based heavely on Jon Skarpeteig Jenkinsfile GIST (3)

The sample Jenkinsfile from that GIST was indeed the best example that I could find on how to move from the php-jenkins-template, to a proper Jenkins pipeline with almost the same functionality. Thank you Jon for publishing the GIST!

The only two things that are missing is the Crap4j (7) publishing (couldn’t manage to make it work at all) and the publishing of the pdepend svg images (which is possible to setup, but I postponed that to another day).

Hope this helps to make your migration from Jenkins 1 with this template, to a proper Jenkins 2 pipeline easier.


Gotchas that i found:

You may want to parallelize the stages as some take a huge amount of time. The worst of them is PHPDox which has been greatly improved in recent versions.

The best solution here is to run PGPDox as a “downstream” job, with access to the “upstream” job.

Another option would be to split the stages in testing (lint + phpunit without coverage) and everything else (+ phpunit with coverage). This doesn’t affect me as much because I run the tools on my machine (through PHPStorm / Intellij Idea).

Be wary that there are two different syntaxes / flavors for Jenkinsfile: scripted (which is what I used here) and declarative (which is stricter, but also more feature rich). If you can, use the declarative and migrate all the stages to it.

Some of the styling in the reports may be missing due to Jenkins content permissions.

I worked around the issue by setup NGINX (8) as a proxy and making those files directly accessible with alias. You can use any proxy to the same effect, just avoid changing Jenkins sandboxing permissions, they are there for a reason!

Hope this is of help to someone, please comment, tweet, pass the message.


Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade