Continuous Integration for PHP on XAMPP

What follows is a long list of tools, configuration settings, and instructions for setting up a continuous integration server for PHP on XAMPP.

Continuous Integration for PHP on XAMPP

Context

DATE /T
2012/01/29
php -v
PHP 5.3.8 (cli) (built: Aug 23 2011 11:50:20)
Copyright (c) 1997-2011 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2011 Zend Technologies
with Xdebug v2.1.2, Copyright (c) 2002-2011, by Derick Rethans
Jenkins
Java Web Archive (.war)
Latest and Greatest 1.449
ant -version
Apache Ant(TM) version 1.8.2 compiled on December 20 2010
ppw --version
PHP Project Wizard (PPW) 1.0.4 by Sebastian Bergmann.
java -version
java version "1.7.0_02"
Java(TM) SE Runtime Environment (build 1.7.0_02-b13)
Java HotSpot(TM) Client VM (build 22.0-b10, mixed mode, sharing)
Netbeans
Product Version: NetBeans IDE 7.1 (Build 201112071828)
Java: 1.7.0_02; Java HotSpot(TM) Client VM 22.0-b10
System: Windows XP version 5.1 running on x86; Cp1252; en_US (nb)
User directory: C:\xampp\userDirectories\netbeans\7.1\default
Cache directory: C:\xampp\userDirectories\netbeans\7.1\default\var\cache

Mandatory Gibberish

Xdebug

In order for the tools I'm talking about to fully function you'll need to have Xdebug installed and enabled. You'll find documentation and installation instructions at http://xdebug.org/ Also, you'll be able to download the binary file for windows. Check the site for the latest version.

Java Developer Kit

The Java Developer Kit contains additional tools that are needed by many advanced tools. There are many tools that won't work with the Java Runtime Environment because they're developer applications and need developers tools. Download the JDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html

Jenkins

Jenkins is a continuous integration server. By itself, Jenkins doesnt do much. Think of it as a container for other tools. The tools you integrate with it will have a handy interface so you can check the state of your code at any time. The idea is to make it easy (non-tedious) to analyze your project and find errors as they're written, instead of after they've been buried under hours or days worth of work. It takes a bit of patience, and if you're not familiar with the tools you're integrating into Jenkins it can be frustrating but, in the end it's worth the effort. Download Jenkins from http://jenkins-ci.org/

Apache Ant

Apache Ant is a build tool. Instead of writing batch files, you write xml files that define tasks and use ant to run those tasks. Once you've got the gist of the xml files it's easy to create new tasks. Many IDE's and other tools have Ant support built in, it's really a great tool to have and know how to use. Download Ant from http://ant.apache.org/bindownload.cgi

PHP Project Wizard

On the site http://jenkins-php.org/, mentioned below, there are instructions for setting up Jenkins Jobs for PHP Projects. Near the bottom of the page, the PHP Project Wizard is mentioned. While it did not work for me without doing quite a bit of editing to the files it created, it did give me a start in the right direction. You don't really need to install it, but it may benefit you to run it at least once and look at the generated files. PPW is installed through Pear, you can read more about the project and get the latest instructions here https://github.com/sebastianbergmann/php-project-wizard

Template for Jenkins Jobs for PHP Projects

On the site http://jenkins-php.org/ there are instructions for setting up Jenkins. Everything seems straightforward when you're reading the directions but, if you're trying to do it on windows you'll fail. There are a few differences in the way you'll have to write the build.xml file in order for Ant to be able to do it's job on windows. There are a few differences in how Jenkins is set up to work with XAMPP. Finally, there are a few batch files to write to get things started up properly. I'll try to provide good information that is easy to understand but, we're about to start juggling six balls in one hand here. Once it's all set up the juggling will be done in the background and all that will be left to do is click a link and see results, it's worth putting in the work here. So, open http://jenkins-php.org/ in another tab, follow the directions, and edit the steps as outlined below in "Mashing it all together".

Mashing it All Together

Download the files located at https://gist.github.com/gists/1701198/download. There are other ways to get this gist:

gist: 1701198 Description: Continuous Integration for PHP on XAMPP Public Clone URL: git://gist.github.com/1701198.git

Explanation of downloaded files

altered_xampp_shell.bat

added the following lines

SET ANT_HOME=\xampp\apache_ant
SET JAVA_HOME=\xampp\jdk
SET CLASSPATH=
SET PATH=%ANT_HOME%\bin;%JAVA_HOME%\bin;%PATH%

Apache Ant requires the environment variable ANT_HOME. The installation instructions for Apache Ant advise setting the CLASSPATH as empty. Many Java programs require the environment variable JAVA_HOME. Adding ANT_HOME and JAVA_HOME to the path is necessary so that Ant and the JDK will function from the command line. Note that this does not permanently alter the PATH and is only effective per instance of the command interpreter invoked from this batch file. If you attempt to run a batch file from the prompt generated by this batch file and you receive errors or odd behavior, try CALL otherfile.bat.

From these lines it is obvious that the files for Ant are to be placed in \xampp\apache_ant. The folder apache_ant will contain all the files from the Ant distribution.

\XAMPP\apache_ant
├───bin
├───docs
├───etc
└───lib

From these lines it is obvious that the files from the JDK are to be placed in \xampp\jdk

\XAMP\jdk
├───bin
├───db
├───include
├───jre
└───lib

jenkins.bat

@echo off
TITLE Jenkins Server
set Path=\xampp\jdk\bin;%Path%
set JENKINS_HOME=\xampp\Jenkins\Home
java -jar jenkins.war

Adds Java Developer Kit's bin file to the path so the war file will run. Sets JENKINS_HOME directory as a subfolder of Jenkins directory in xampp. Initially you'll only have the war file and this batch file in the Jenkins directory. Once you run the bat file Java will extract the war file to the Jenkins directory. You should always start Jenkins using the batch file so you know that your data is being written to the Home directory.

\xampp
├───apache_ant
├───jdk
├───Jenkins
│ ├───jenkins.bat
│ └───jenkins.war
└───php

build.xml

This is the Ant build file to use instead of the one you can copy or download from http://jenkins-php.org/. Place it in the root of your project.

\xampp\htdocs\myProject\build.xml

config.xml

This file is a default setup for jobs. When you get to the section of http://jenkins-php.org/ labeled "Using the Job Template", download the job template "php-template" and replace the config.xml file in it with this one.

\xampp\Jenkins\Home\jobs\php-template\config.xml

netbeans.conf

This file is for Netbeans. Netbeans comes with built in support for phpunit and svn. They've also got excellent documentation on how to set it up. Basically you set the general options for Netbeans by telling it the location of phpunit.bat and svn.exe. Then, in your project settings you set the tests folder as your "tests directory". It's that simple. You right click on a file and there are options to run the test or have phpunit report on code coverage. You can also run all tests and generate code coverage reports on the entire project. The code coverage report displays a percentage of code covered for each file and also highlights the source code to show what is covered and what is not covered. It's very handy stuff. The subversion support is good, you have to create the repository using a single command on the command line, but after that you can do pretty much everything from the IDE. Like I said, their documentation is excellent, if you want to use Netbeans to take advantage of these features, I've included this configuration file to get you up and running a bit faster. Place this configuration file in \xampp\netbeans\etc

The version of Netbeans to download is 7.1. On the download page, be sure to change the platform to "OS Independent Zip".

Create the directory structure \xampp\userDirectories\netbeans\7.1\default\, or change the setting in this configuration file and create the user settings folder somewhere else.

Jenkins Settings

Changing the Workspace Directory

In order to have your project files located at \xampp\htdocs\myProject, it is necessary to change a configuration option in Jenkins. Otherwise, your project will have to be located at \xampp\Jenkins\Home\workspace\myProject. Having the project located there could be problematic for your IDE or other tools you may want to use.

The setting to change the default workspace directory is located at http://localhost:8080/configure. At the top of the page you'll see the read only setting "Home directory". Just below that setting and all the way to the right of the page there is a button labeled "Advanced", click it. Two new configuration options will now be exposed, set them to match the following:

Workspace Root Directory /xampp/htdocs/${ITEM_FULLNAME}

Build Record Root Directory ${ITEM_ROOTDIR}/builds

Set JDK and Ant Locations

Scroll down the page until you get to the section labeled "JDK". Click "Add JDK" fill in the name as jdk and the JAVA_HOME as \xampp\jdk\

Scroll down the page until you get to the section labeled "Ant". Click "Add Ant" fill in the name as ant and the ANT_HOME as \xampp\apache_ant

Click the save button floating at the bottom left hand side of the screen.

Directory Structure of PHP Projects

The directory structure for PHP projects remains the same as is explained on http://jenkins-php.org/ however, I thought it may be helpful if I lay it out visually here.

\XAMPP\HTDOCS\myProject
├───build
├───src
└───tests

Obviously, the src folder will contain the files and directories of your project. The tests folder will contain your PHPUnit tests. The build folder will be populated with files and folders generated by the Ant build script and Jenkins. If you want to change the directory structure you'll have to find the relevant settings in build.xml, config.xml, or any other file which sets up an expectation of finding this particular directory structure.

Adding Netbeans

Download the latest version of the zip archive. You can get it by changing the "platform" option to "OS Independent Zip". You can chose the package with built in PHP support or you can chose one that doesn't have it built in and try figuring out what plugins you have to download. . . After you download the zip file extract it and put the contents into a folder at \xampp\netbeans\

\XAMPP\NETBEANS
├───bin
├───etc
├───harness
│ ├───antlib
│ ├───config
│ │ └───Modules

Adding Subversion

Download the zip version of the windows binaries from http://alagazam.net/ and unzip it to \xampp\subversion The command line client will work right away. If you want, you could add \xampp\subversion\bin to the path in altered_xampp_shell.bat and have easy access to it from anywhere within the xampp shell. You can also integrate subversion into the build process using either Ant or Jenkins, depending on what you want to do and when. Creating a repository is as easy as running the command:

\xampp\subversion\bin\svnadmin.exe create \xampp\repository

Embedded Gist

Clone it: git clone git://gist.github.com/3709227.git gist-3709227

Matthew Kastor

Labels