Using PHP static analysis tools with Jenkins

In the last article I went over the various static analysis tools I’ve found useful, and how to get them installed. For this installment, I’ll be going over how to use make to run all the tasks, and how to configure all the tools to work with Jenkins. make is a decent build/scripting tool, that I like to use becauase its dead simple. There are many other tools you can use to accomplish what I’m showing here, but I find make to be the simplest. If you really hate make you can easily re-implement this with fabric, rake or gruntjs.

While installing Jenkins is a bit out of scope for this article, the Jenkins wiki has a great installation tutorial that should get you up and running. After getting Jenkins installed a few additional plugins are required to make graphs, and track your progress:

• DRY Plugin is used to visualize reports from PHPcpd.
• Checkstyle is used to visualize the reports from phpcs.
• Violations is used to plot both Checkstyle and DRY results on the same set of axis, and is good for comparing and tracking results over time.

All of these plugins can be installed from inside of Jenkins, by going to Manage Jenkins > Manage plugins. Both the DRY and Checkstyle plugins have a bunch of configuration options and even allow you to fail builds should the errors they detect cross a threshold. This is great once you’ve gotten your project squeaky clean and want to prevent future transgressions.

Creating a Makefile

After installing all the plugins into Jenkins, we’ll add a Makefile. We’ll be using make to wrap up the various options that each static analysis tool uses, and give us an easy way to run the checks locally and in Jenkins:

Save this as Makefile in the root of your project. Before saving the file, make sure the indentation uses hard tabs. Make is very picky and will only accept tabs for indentation. We add a few tasks to .IGNORE as we don’t want make to stop running when those tasks exit non-zero. However, we do want jshint errors to cause a build failure. To run a task you simply call make check-style for example. Make will run the commands, and display the output. Now that we have a Makefile we can configure the Jenkins plugins and add the build required build steps.

Configuring Jenkins

After creating the Makefile and installing all the plugins in Jenkins its time to configure each of the plugins. If you already have a build defined for your project, you can just append this configuration to it. If not you can start a new build, and add the following configuration to it.

Configure DRY

The DRY plugin maps the results from php-cpd. Its configuration looks like:

The only required configuration is the filename. All other configuration is optional. And unless your project has rampant duplicate code you probably won’t need to trigger build failures based on the outcome of this check.

Configure Checkstyle

The Checkstyle plugin plots results from phpcs. Its configuration looks like:

The most important thing to do is set the filename.for the checkstyle.xml. Doing only this will enable jenkins to start graphing and creating reports. You can use the additional configuration options to force build failures if the number of errors or warnings crosses a certain threshold. If you’re working with a project that has a high number for errors, a strategy I’ve found successful is to set the build failure to the high water mark. Then on each successful build, update the high water mark to reflect the new lower value. Given enough time and effort you’ll get to zero.

Configure violations

The violations plugin lets you combine both of the previous graphs on the same axis. This lets you compare them and track the collective progress over time.

After configuring each of the plugins you’ll also need to add a new Execute Shell build step. In it put:

This will trigger all the checks on each build, and generate all the graphs. Before running your first build, be sure to install all the static analysis tools on the machine running Jenkins as well. Jenkins will need access to the various tools in-order to run them.

That’s pretty much all there is to integrating static analysis tools with Jenkins. You’ll be well on your way to knowing more about your code and getting your team’s conventions and best practices enforced by heartless robots. In addition to that you have a basic Makefile you can easily add new tools, or other build related tasks like asset compression into.