Phing Build File General default build file for automating a PHP project

Share

Screenshot of Jenkins

Jenkins, powered by my Phing build file

On my computer I have Jenkins installed for viewing analysis of code, and as I code with PHP and not Java, I use Phing instead of Ant as the build system. I run several PHP programs against the code I’ve written or auditing, and automate the creation of API documentation using DocBlox, as well as send that documentation via FTP to a docs subdomain.

I’ve refined my build file over time, but it has always been pretty much an identical file duplicated over many projects, and this wasn’t scaling well as I found the need to refine it further. Instead, I discovered the ImportTask in Phing, which meant I could have one generic build file kept outside of my project folders, and import that into each bare bones project build file and amend as necessary.

Here’s my generic build file code (obviously you may have a different set of targets and procedures you want to undertake like unit testing, deploying to git or svn, etc.):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374
<?xml version="1.0" encoding="UTF-8"?>
 
<!--
This is a default build file that sits outside of any project folders, but
which is imported into the project build file like so:
<import file="../../build.xml"/>
All relative references in this file, are assumed to be from the base of the
project build file.
If an identically named target in the project build file is also present in
this imported file, the one from the project file takes precedence. e.g. a
project build file can define a different "build" target to remove the ftp and
ftp-htaccess targets, for instance.
-->
 
<project name="builddefault" default="build" description="Jenkins">
 
<target name="build" depends="init, clean, verify, analyze, dist, docs" description="Do a full build"/>
 
<target name="verify" depends="init, clean, lint" description="Verify the quality of the code"/>
 
<target name="analyze" depends="init, clean, phploc, pdepend, phpmd-ci, phpcs-ci, phpcs-, phpcpd" description="Do static analysis of the code"/>
 
<target name="docs" depends="init, clean, phpdoc, phpcb, htaccess, copysvg, copybuild, ftp"/>
 
<target name="init" depends="-load-properties, -setup-dirs, -setup-filesets" unless="project.initialised">
<property name="project.initialised" value="true"/>
</target>
 
<target name="-load-properties">
<!-- Take a project name and make it safe for use as directory or file names -->
<php expression="str_replace(' ', '-', strtolower('${phing.project.name}'))" returnProperty="project.name.safe"/>
 
<!--
The ${phing.file.builddefault} value is the path to this imported file.
The property name matches the name attribute above for the project in this file.
-->
<php function="dirname" returnProperty="imported.base.dir">
<param value="${phing.file.builddefault}"/>
</php>
<!-- Pull in the global / default properties -->
<property file="${imported.base.dir}/build.default.properties" override="true"/>
 
<!--
Pull in the per-project properties.
Since this build file is imported into other build files, this line
loads the build.properties file in reference to the project build.xml file
i.e. project/build/build.properties, and overrides the global defaults.
-->
<property file="build.properties" override="true"/>
 
<!--
The project version is nearly always in the per-project build file, so here
we set the FTP upload directory that includes the version number.
-->
<property name="ftp.dir" value="${ftp.project.dir}/${project.version}" override="true"/>
 
<!-- Sets a stable version (used in .htaccess) if one has not already been set. -->
<property name="project.stable.version" value="${project.version}"/>
 
</target>
 
<target name="-setup-dirs" depends="-load-properties">
<!-- My project set up is as follows:
 
ProjectName
- build (all the build file stuff)
- - api (phpDocumentor-generated API documentation which is later uploaded via FTP)
- - code-browser (phpcb-generated code browser)
- - dist (distributable zip file of source generated here)
- - logs (log files from static analysis)
- - pdepend (SVG images generated from PHP_Depend)
- src (the actual source)
- nbproject (Netbeans project stuff)
 
By default the Phing built-in property $project.basedir points to my build file directory,
so here, we grab the path to the level above, and then create friendlier aliases.
-->
<php function="dirname" returnProperty="project.dir">
<param value="${project.basedir}"/>
</php>
<property name="build.dir" value="${project.dir}\build"/>
<property name="src.dir" value="${project.dir}\src"/>
<property name="docs.dir" value="${project.dir}\docs"/>
<property name="tests.dir" value="${project.dir}\tests"/>
 
<echo message="Assigning build directories to properties" level="debug"/>
<property name="build.api.dir" value="${build.dir}/api"/>
<property name="build.codebrowser.dir" value="${build.dir}/code-browser"/>
<property name="build.dist.dir" value="${build.dir}/dist"/>
<property name="build.logs.dir" value="${build.dir}/logs"/>
<property name="build.pdepend.dir" value="${build.dir}/pdepend"/>
</target>
 
<target name="-setup-filesets">
<patternset id="php">
<include name="**/*.php"/>
</patternset>
 
<patternset id="tests">
<include name="**/*Test.php"/>
</patternset>
 
<patternset id="js">
<!-- Don't include minified files as they won't pass code standards -->
<include name="**/*.js"/>
<exclude name="**/*.min.js"/>
</patternset>
 
<patternset id="css">
<!-- Don't include minified files as they won't pass code standards -->
<include name="**/*.css"/>
<exclude name="**/*.min.css"/>
</patternset>
 
<patternset id="zip">
<!-- Exclude Mac / Windows / version control artifacts from zip -->
<exclude name="**/.DS_Store"/>
<exclude name="**/Thumbs.db"/>
<exclude name=".svn/"/>
<exclude name=".git/"/>
</patternset>
 
<patternset id="svg">
<include name="**/*.svg"/>
</patternset>
 
<fileset dir="${src.dir}" id="php.files">
<patternset refid="php"/>
</fileset>
 
<fileset dir="${src.dir}" id="js.files">
<patternset refid="js"/>
</fileset>
 
<fileset dir="${src.dir}" id="css.files">
<patternset refid="css"/>
</fileset>
 
<fileset dir="${src.dir}" id="zip.files">
<patternset refid="zip"/>
</fileset>
 
<fileset dir="${build.pdepend.dir}" id="pdepend.svg.files">
<patternset refid="svg"/>
</fileset>
 
<fileset dir="${tests.dir}" id="test.files">
<patternset refid="tests"/>
</fileset>
 
<property name="coding-standards.file" value="${project.name.safe}-coding-standards.txt"/>
</target>
 
<target name="clean" depends="init" unless="project.cleaned">
<!-- Remove previous build subdirectories, and recreate fresh versions -->
<echo message="Deleting build directories" level="debug"/>
<delete dir="${build.api.dir}"/>
<delete dir="${build.codebrowser.dir}"/>
<delete dir="${build.logs.dir}"/>
<delete dir="${build.pdepend.dir}"/>
 
<echo message="Creating build directories" level="debug"/>
<mkdir dir="${build.api.dir}"/>
<mkdir dir="${build.codebrowser.dir}"/>
<mkdir dir="${build.dist.dir}"/>
<mkdir dir="${build.logs.dir}"/>
<mkdir dir="${build.pdepend.dir}"/>
 
<property name="project.cleaned" value="true"/>
</target>
 
<target name="dist" depends="init" description="Create distributable file">
<!--
Within the dist folder, create a subfolder by the name of the project, and a sub-subfolder
to that, also with the name of the project.
By creating this extra level, we can then move the sub-subfolder into the zip file. This folder
can then be extracted from the zip in one go (and it's how WordPress plugins and theme should be)
rather than the zip containing individual files as immediate children.
-->
<property name="build.dist.temp.dir" value="${build.dist.dir}/${project.name.safe}"/>
<property name="build.dist.zip.root.dir" value="${build.dist.temp.dir}/${project.name.safe}"/>
 
<mkdir dir="${build.dist.temp.dir}"/>
<mkdir dir="${build.dist.zip.root.dir}"/>
<copy todir="${build.dist.zip.root.dir}">
<fileset refid="zip.files"/>
</copy>
 
<zip destfile="${build.dist.dir}/${project.name.safe}-${project.version}.zip">
<fileset dir="${build.dist.temp.dir}/"/>
</zip>
 
<!--
We're finished with the temporary folder and it's subfolder, so delete them (deleting
the parent temp folder is enough).
-->
<delete dir="${build.dist.temp.dir}"/>
</target>
 
<target name="lint" depends="init" description="Check files for syntax errors">
<phplint haltonfailure="true" cachefile="${build.logs.dir}/cachefile.txt">
<fileset refid="php.files"/>
</phplint>
</target>
 
<target name="phpunit" depends="init" description="Run unit tests">
<!--<phpunit printsummary="true" haltonfailure="true" bootstrap="${tests.dir}\bootstrap.php">-->
<phpunit printsummary="true" bootstrap="${tests.dir}\bootstrap.php">
<!--<formatter todir="${logs.dir}" type="xml"/>-->
<batchtest>
<fileset refid="test.files"/>
</batchtest>
</phpunit>
</target>
 
<target name="phploc" depends="init" description="Measure project size using PHPLOC">
<exec executable="phploc" logoutput="true" checkreturn="true" level="debug">
<arg value="--log-csv"/>
<arg value="${build.logs.dir}/phploc.csv"/>
<arg path="${src.dir}"/>
</exec>
</target>
 
<target name="pdepend" depends="init" description="Calculate software metrics using PHP_Depend">
<phpdepend>
<fileset refid="php.files"/>
<logger type="jdepend-xml" outfile="${build.logs.dir}/jdepend.xml"/>
<logger type="summary-xml" outfile="${build.logs.dir}/jdepend-summary.xml"/>
<logger type="jdepend-chart" outfile="${build.pdepend.dir}/dependencies.svg"/>
<logger type="overview-pyramid" outfile="${build.pdepend.dir}/overview-pyramid.svg"/>
</phpdepend>
</target>
 
<target name="phpmd-ci" depends="init" description="Perform project mess detection using PHPMD">
<phpmd rulesets="codesize,design,naming,unusedcode">
<fileset refid="php.files"/>
<formatter type="xml" outfile="${build.logs.dir}/pmd.xml"/>
</phpmd>
</target>
 
<!--
This almost duplication of the above target, is so that it can be run standalone in the command
line, and have the results echoed to screen, instead of a file.
-->
<target name="phpmd" depends="init" description="Perform project mess detection using PHPMD">
<phpmd rulesets="codesize,design,naming,unusedcode">
<fileset refid="php.files"/>
</phpmd>
</target>
 
<target name="phpcs-ci" depends="init" description="Find coding standard violations using PHP_CodeSniffer">
<phpcodesniffer standard="${phpcs.standard}" tabWidth="${phpcs.tabWidth}" encoding="${phpcs.encoding}">
<fileset refid="php.files"/>
<formatter type="checkstyle" outfile="${build.logs.dir}/checkstyle.xml"/>
</phpcodesniffer>
</target>
 
<!--
This almost duplication of the above target, is so that it can be run standalone in the command
line, and have the results echoed to screen, instead of a file.
-->
<target name="phpcs" depends="init" description="Find coding standard violations using PHP_CodeSniffer">
<phpcodesniffer standard="${phpcs.standard}" tabWidth="${phpcs.tabWidth}" encoding="${phpcs.encoding}">
<fileset refid="php.files"/>
</phpcodesniffer>
</target>
 
<!--
This version creates a simple text report of CS issues which can then be uploaded to show the client.
-->
<target name="phpcs-" depends="init" description="Find coding standard violations using PHP_CodeSniffer">
<phpcodesniffer standard="${phpcs.standard}" tabWidth="${phpcs.tabWidth}" encoding="${phpcs.encoding}">
<fileset refid="php.files"/>
<formatter type="emacs" outfile="${build.logs.dir}/${coding-standards.file}"/>
</phpcodesniffer>
<reflexive file="${build.logs.dir}/${coding-standards.file}">
<filterchain>
<replaceregexp>
<regexp pattern="C:\.*\src\" replace=""/>
</replaceregexp>
</filterchain>
</reflexive>
</target>
 
<target name="phpcpd" depends="init" description="Find duplicate code using PHPCPD">
<phpcpd minLines="10" minTokens="20">
<fileset refid="php.files"/>
<formatter type="pmd" outfile="${build.logs.dir}/pmd-cpd.xml"/>
</phpcpd>
</target>
 
<target name="phpdoc" depends="init" description="Generate API documentation">
<phpdoc2 title="${phing.project.name} ${project.version}" destdir="${build.api.dir}">
<fileset dir="${src.dir}"/>
</phpdoc2>
 
</target>
 
<target name="phpcb" depends="init" description="Aggregate tool output with PHP_CodeBrowser">
<exec executable="phpcb" logoutput="true" checkreturn="true" level="debug">
<arg value="--log"/>
<arg path="${build.logs.dir}"/>
<arg value="--source"/>
<arg path="${src.dir}"/>
<arg value="--output"/>
<arg path="${build.codebrowser.dir}"/>
</exec>
</target>
 
<target name="htaccess" depends="init" description="Create .htaccess file for docs">
<!-- Redirects http://docs.example.com/projectname to http://docs.example.com/projectname/version -->
<echo file="${build.dir}/.htaccess">
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/${project.name.safe}/?$
RewriteRule ^(.*) ${ftp.baseurl}${project.name.safe}/${project.stable.version} [R=301,L]
</echo>
</target>
 
<target name="copysvg" depends="init" description="Copy PHP_Depend SVGs to Jenkins workspace folder">
<copy todir="${jenkins.workspace.dir}">
<fileset refid="pdepend.svg.files"/>
</copy>
</target>
 
<target name="copybuild" depends="init" description="Copy build directory to Jenkins workspace folder so it can be archived">
<mkdir dir="${jenkins.workspace.dir}/build"/>
<copy todir="${jenkins.workspace.dir}/build">
<fileset dir="${build.dir}"/>
</copy>
</target>
 
<target name="ftp" depends="init" description="Upload API docs">
<echo msg="Doing FTP: Copying ${build.api.dir} to ${ftp.host}${ftp.dir}. Please wait..."/>
<ftpdeploy
host="${ftp.host}"
username="${ftp.username}"
password="${ftp.password}"
dir="${ftp.dir}"
passive="${ftp.passive}">
<fileset dir="${build.api.dir}"/>
</ftpdeploy>
<phingcall target="ftp-htaccess"/>
<phingcall target="ftp-phpcs"/>
</target>
 
<target name="ftp-htaccess" depends="init" description="Upload .htaccess file">
<echo msg="Doing FTP: Copying .htaccess to ${ftp.host}${ftp.project.dir}"/>
<ftpdeploy
host="${ftp.host}"
username="${ftp.username}"
password="${ftp.password}"
dir="${ftp.project.dir}"
passive="${ftp.passive}">
<fileset dir="${build.dir}">
<include name=".htaccess"/>
</fileset>
</ftpdeploy>
</target>
 
<target name="ftp-phpcs" depends="init" description="Upload coding standards file">
<echo msg="Doing FTP: Copying coding standards file to ${ftp.host}${ftp.dir}"/>
<ftpdeploy
host="${ftp.host}"
username="${ftp.username}"
password="${ftp.password}"
dir="${ftp.dir}"
passive="${ftp.passive}">
<fileset dir="${build.logs.dir}">
<include name="${coding-standards.file}"/>
</fileset>
</ftpdeploy>
</target>
 
</project>
view raw builddefault.xml hosted with ❤ by GitHub

And then each project build file is simply:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<?xml version="1.0" encoding="UTF-8"?>
 
<project name="Project Name" default="build" description="Jenkins">
 
<import file="../../builddefault.xml"/>
 
<!--
Overwrite individual targets - can leave empty to stop a called target
from having any effect.
-->
<!--
<target name="..."></target>
-->
 
</project>
view raw build.xml hosted with ❤ by GitHub

If I want to create a tweaked target for a particular project, then I can simply add that to the project build file (as per the commented-out section), and it takes precedence over the generic target of the same name. An example of this is the following, which adds a custom target when parsing the coding standards for the WordPress project, so it can exclude all of the 3rd party libraries that won’t be expected to follow the coding standards:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
<?xml version="1.0" encoding="UTF-8"?>
 
<project name="WordPress" default="build" description="Jenkins">
 
<import file="../../builddefault.xml" />
 
<target name="phpcs-" depends="init" description="Find coding standard violations using PHP_CodeSniffer">
<phpcodesniffer standard="${phpcs.standard}" tabWidth="${phpcs.tabWidth}" encoding="${phpcs.encoding}">
<fileset dir="${src.dir}">
<include name="**/*.php"/>
<exclude name="wp-admin/includes/class-ftp-pure.php"/>
<exclude name="wp-admin/includes/class-ftp-sockets.php"/>
<exclude name="wp-admin/includes/class-ftp.php"/>
<exclude name="wp-admin/includes/class-pclzip.php"/>
<exclude name="wp-includes/Text/"/>
<exclude name="wp-includes/js/tinymce/plugins/"/>
<exclude name="wp-includes/class-IXR.php"/>
<exclude name="wp-includes/class-json.php"/>
<exclude name="wp-includes/class-phpass.php"/>
<exclude name="wp-includes/class-phpmailer.php"/>
<exclude name="wp-includes/class-pop3.php"/>
<exclude name="wp-includes/class-simplepie.php"/>
<exclude name="wp-includes/class-smtp.php"/>
<exclude name="wp-includes/class-snoopy.php"/>
</fileset>
<formatter type="emacs" outfile="${build.logs.dir}/${coding-standards.file}"/>
</phpcodesniffer>
<reflexive file="${build.logs.dir}/${coding-standards.file}">
<filterchain>
<replaceregexp>
<regexp pattern="C:\.*\src\" replace=""/>
</replaceregexp>
</filterchain>
</reflexive>
</target>
 
</project>
view raw wordpress-build.xml hosted with ❤ by GitHub

That default build file pulls in both a global default properties file, and a per-project properties file too, with the properties in the latter taking precedence. Here’s an example of my global default properties file:

1 2 3 4 5 6 7 8 9 10 11 12 13
phpcs.standard = WordPress
phpcs.tabWidth = 4
phpcs.encoding = utf-8
 
ftp.host = ftp.example.com
ftp.port = 21
ftp.username = username
ftp.password = password
ftp.project.dir = /subdomains/docs/httpdocs/${project.name.safe}
ftp.dir = ${ftp.project.dir}/${project.version}
ftp.baseurl = http://docs.example.com/
 
jenkins.workspace.dir = C:\Program Files\Jenkins\jobs${phing.project.name}\workspace

Which leaves a typical per-project properties file down to the bare basics:

1 2 3 4 5 6
project.version = 1.1.0-beta
 
# Optional, if docs for latest version should not overwrite stable version docs.
project.stable.version = 1.0.0
 
# Any of the other properties from the build.default.properties file can be re-defined here.
view raw build.properties hosted with ❤ by GitHub

Comments

  1. Carlton says:

    Thanks, really helpful example build file

Speak Your Mind

*