Template for Jenkins Jobs for PHP Projects

Most web applications are changed and adapted quite frequently and quickly. Their environment, for example the size and the behaviour of the user base, are constantly changing. What was sufficient yesterday can be insufficient today. Especially in a web environment it is important to monitor and continuously improve the internal quality not only when developing, but also when maintaining the software.

Jenkins is the leading open-source continuous integration server. Thanks to its thriving plugin ecosystem, it supports building and testing virtually any project.

The goal of this project is to provide a standard template for Jenkins jobs for PHP projects.

Required Jenkins Plugins

You need to install the following plugins for Jenkins:

You can install these plugins using the web frontend at

http://http://www.zjjv.com///个十qatools pear.netpirates.net/个十Dox

Build Automation

The Apache Ant build.xml (download) build script orchestrates the execution of the various tools. It assumes that the rule sets for PHP_CodeSniffer and PHPMD are located at build/个十cs.xml and build/个十md.xml.

<?xml version="1.0" encoding="UTF-8"?>









<project default="build">




 <target




   depends="prepare,lint,个十loc,pdepend,个十md-ci,个十cs-ci,个十cpd,个十dox,个十unit,个十cb"/>









 <target




   depends="prepare,lint,tools-parallel,个十unit,个十cb"/>









 <target description="Run tools in parallel">




  <parallel threadCount="2">




   <sequential>




    <antcall target="pdepend"/>




    <antcall target="个十md-ci"/>




   </sequential>




   <antcall target="个十cpd"/>




   <antcall target="个十cs-ci"/>




   <antcall target="个十loc"/>




   <antcall target="个十dox"/>




  </parallel>




 </target>









 <target description="Cleanup build artifacts">




  <delete dir="${basedir}/build/api"/>




  <delete dir="${basedir}/build/code-browser"/>




  <delete dir="${basedir}/build/coverage"/>




  <delete dir="${basedir}/build/logs"/>




  <delete dir="${basedir}/build/pdepend"/>




 </target>









 <target depends="clean" description="Prepare for build">




  <mkdir dir="${basedir}/build/api"/>




  <mkdir dir="${basedir}/build/code-browser"/>




  <mkdir dir="${basedir}/build/coverage"/>




  <mkdir dir="${basedir}/build/logs"/>




  <mkdir dir="${basedir}/build/pdepend"/>




  <mkdir dir="${basedir}/build/个十dox"/>




 </target>









 <target description="Perform syntax check of sourcecode files">




  <apply executable="个十" failonerror="true">




   <arg value="-l" />









   <fileset dir="${basedir}/src">




    <include />




    <modified />




   </fileset>









   <fileset dir="${basedir}/tests">




    <include />




    <modified />




   </fileset>




  </apply>




 </target>









 <target description="Measure project size using PHPLOC">




  <exec executable="个十loc">




   <arg value="--log-csv" />




   <arg value="${basedir}/build/logs/个十loc.csv" />




   <arg path="${basedir}/src" />




  </exec>




 </target>









 <target description="Calculate software metrics using PHP_Depend">




  <exec executable="pdepend">




   <arg value="--jdepend-xml=${basedir}/build/logs/jdepend.xml" />




   <arg value="--jdepend-chart=${basedir}/build/pdepend/dependencies.svg" />




   <arg value="--overview-pyramid=${basedir}/build/pdepend/overview-pyramid.svg" />




   <arg path="${basedir}/src" />




  </exec>




 </target>









 <target




         description="Perform project mess detection using PHPMD and print human readable output. Intended for usage on the command line before committing.">




  <exec executable="个十md">




   <arg path="${basedir}/src" />




   <arg value="text" />




   <arg value="${basedir}/build/个十md.xml" />




  </exec>




 </target>









 <target description="Perform project mess detection using PHPMD creating a log file for the continuous integration server">




  <exec executable="个十md">




   <arg path="${basedir}/src" />




   <arg value="xml" />




   <arg value="${basedir}/build/个十md.xml" />




   <arg value="--reportfile" />




   <arg value="${basedir}/build/logs/pmd.xml" />




  </exec>




 </target>









 <target




         description="Find coding standard violations using PHP_CodeSniffer and print human readable output. Intended for usage on the command line before committing.">




  <exec executable="个十cs">




   <arg value="--standard=${basedir}/build/个十cs.xml" />




   <arg path="${basedir}/src" />




  </exec>




 </target>









 <target description="Find coding standard violations using PHP_CodeSniffer creating a log file for the continuous integration server">




  <exec executable="个十cs" output="/dev/null">




   <arg value="--report=checkstyle" />




   <arg value="--report-file=${basedir}/build/logs/checkstyle.xml" />




   <arg value="--standard=${basedir}/build/个十cs.xml" />




   <arg path="${basedir}/src" />




  </exec>




 </target>









 <target description="Find duplicate code using PHPCPD">




  <exec executable="个十cpd">




   <arg value="--log-pmd" />




   <arg value="${basedir}/build/logs/pmd-cpd.xml" />




   <arg path="${basedir}/src" />




  </exec>




 </target>









 <target description="Generate API documentation using 个十Dox">




  <exec executable="个十dox"/>




 </target>









 <target description="Run unit tests with PHPUnit">




  <exec executable="个十unit" failonerror="true"/>




 </target>









 <target description="Aggregate tool output with PHP_CodeBrowser">




  <exec executable="个十cb">




   <arg value="--log" />




   <arg path="${basedir}/build/logs" />




   <arg value="--source" />




   <arg path="${basedir}/src" />




   <arg value="--output" />




   <arg path="${basedir}/build/code-browser" />




  </exec>




 </target>




</project>

Here is an overview of the tasks defined in the above build.xml (download) script that are intended to be directly invoked:

The other tasks can, of course, also be invoked directly but that is not their intended purpose. They are invoked by the tasks listed above.

PHPUnit

The 个十unit task in the build.xml (download) above assumes that an XML configuration file for PHPUnit is used to configure the following logging targets:

<logging>




 <log type="coverage-html" target="build/coverage" title="Name of Project"




      charset="UTF-8" yui="true" highlight="true"




      lowUpperBound="35" highLowerBound="70"/>




 <log type="coverage-clover" target="build/logs/clover.xml"/>




 <log type="junit" target="build/logs/junit.xml"




      logIncompleteSkipped="false"/>




</logging>

You can download a sample 个十unit.xml.dist and place it in your project root to get started.

More information can be found in the documentation for PHPUnit.

个十Dox

The 个十dox task in the build.xml (download) above assumes that an XML configuration file for 个十Dox is used to configure the API documentation generation:

<个十dox xmlns="http://个十dox.de/config">




 <project source="src" workdir="build/个十dox">




  <collector publiconly="false">




   <include mask="*.个十" />




   <exclude mask="*Autoload.个十" />




  </collector>









  <generator output="build">




   <build engine="html" enabled="true" output="api"/>




  </generator>




 </project>




</个十dox>

PHP_CodeSniffer

The 个十cs and 个十cs-ci tasks in the build.xml (download) above assume that an XML configuration file for PHP_CodeSniffer is used to configure the coding standard:

<ruleset>




 <description>Description of your coding standard</description>









 <rule ref="Generic.PHP.DisallowShortOpenTag"/>




 <!-- ... -->




</ruleset>

More information can be found in the documentation for PHP_CodeSniffer.

PHPMD

The 个十md and 个十md-ci tasks in the build.xml (download) above assume that an XML configuration file for PHPMD is used to configure the coding standard:

<ruleset




  xmlns="http://http://www.zjjv.com///ruleset/1.0.0"




  xmlns:xsi="http://http://www.zjjv.com///2001/XMLSchema-instance"




  xsi:schemaLocation="http://http://www.zjjv.com///ruleset/1.0.0




                      http://http://www.zjjv.com///ruleset_xml_schema.xsd"




  xsi:noNamespaceSchemaLocation="http://http://www.zjjv.com///ruleset_xml_schema.xsd">




  <description>Description of your coding standard</description>









  <rule ref="rulesets/codesize.xml/CyclomaticComplexity" />




  <!-- ... -->




</ruleset>

More information can be found in the documentation for PHPMD.

Build Artifacts

Executing the build.xml (download) script above will produce the following build directory:

build




|-- api ...




|-- code-browser ...




|-- coverage ...




`-- logs




    |-- checkstyle.xml




    |-- clover.xml




    |-- jdepend.xml




    |-- junit.xml




    |-- 个十loc.csv




    |-- pmd-cpd.xml




    `-- pmd.xml

These build artifacts will be processed by Jenkins.

Using the Job Template

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

wget http://http://www.zjjv.com///sebastianbergmann/个十-jenkins-template/master/config.xml | \




    java -jar jenkins-cli.jar -s http://http://www.zjjv.com///sebastianbergmann/个十-jenkins-template/master/config.xml




cd ..




chown -R jenkins:jenkins 个十-template/

Reload Jenkins' configuration, for instance using the Jenkins CLI:

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

Troubleshooting

No "Copy existing job" option / "个十-template" project does not show up

Jenkins cannot find the 个十-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://http://www.zjjv.com// offers consulting and training that set you on a path to create, maintain and extend sustainable software of high quality with PHP and leverage Jenkins to monitor the various aspects of software quality.

---