Phing Build File for WordPress Plugin and Theme Projects — Gary's Code: General default build file for automating a PHP project

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.):

    
      
        
        
          <?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
          This Gist brought to you by GitHub.
        

And then each project build file is simply:

    
          <?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
          This Gist brought to you 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 3^rd party libraries that won’t be expected to follow the coding standards:

    
      
        
        
          <?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
          This Gist brought to you 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:

    
          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

          view raw
          build.default.properties
          This Gist brought to you by GitHub.

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

    
          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
          This Gist brought to you by GitHub.

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

Speak Your Mind Cancel reply