Getting started with PHP

Unit tests

Since PHP is an interpreted language, we don't need a compilation step and can immediately start with unit tests: we want to make sure all tests are green every time source code is changed. Whenever there is a failing unit test, we want to fail the entire build and not provide any build artifacts. TeamCity comes with a number of predefined build steps for Java and .NET, but since we're on PHP we'll have to select the Command Line build runner.

We want to run the PHPUnit configuration that's provided with PHPExcel source code. Invoking this can be done using the following command line script:

phpunit \-c phpunit.xml

By default, TeamCity will import the test results provided by PHPUnit. However we can also report real-time test results to TeamCity, so that we can already see results during a build run before it's even finished. Using a wrapper around PHPUnit which uses service messages to report build results. Locate the wrapper somewhere on the build agent or have the build agent download it from the above GitHub repository directly using a second VCS root.

We can already invoke our build configuration and should be getting unit test results displayed. But we're not finished yet, we want to add some more build steps.

Running Phing

Our next build step will be invoking Phing, a PHP project build system or build tool based on ​Apache Ant. PHPExcel comes with a Phing build script which we'll invoke after all unit tests have passed. Let's add a new Command Line build step which uses Phing's command-line tool and pass some parameters to it:

phing \-f build\build.xml \-DpackageVersion=%system.build.number% \-DreleaseDate=CIbuild \-DdocumentFormat=doc release-standard

PHPExcel has four build targets defined (release-standard, release-documentation, release-pear and release-phar ), all providing different build artifacts. The release-standard target which we've now specified at the command line is the default build for PHPExcel which generates a ZIP file containing all source code and phpDocumentor output.

We are also passing Phing the current build number from TeamCity using Phing's -D command line switches. The build script can use these to create the correct file names.

If you haven't configured the artifact paths while creating our build project, it's best to do so now (see Setting up the project). We want to make sure that the ZIP file generated in this build script is available from TeamCity's web interface.

When we run another build, we'll now see that unit tests are being run and afterwards the Phing build script is being run. Once the entire build is completed, we can find the ZIP file generated by the Phing build script as a downloadable build artifact.

Code coverage

The first build step we created was running unit tests using PHPUnit. The nice thing about PHPUnit is that it can provide code coverage information as well, nicely formatted as an HTML report. TeamCity can display HTML reports on a custom tab in the build results.

Let's first make sure code coverage is enabled. Edit the first build step (running PHPUnit) and make sure it uses PHPExcel's phpunit-cc.xml configuration file for configuring PHPUnit. This configuration file which is specific to PHPExcel outputs its code coverage report in the unitTests/codeCoverage folder. While it is possible to add all generated files to TeamCity as a build artifact, it's cleaner to ZIP that entire folder and make it available as one single file. We can have TeamCity create this ZIP file for us by using a special artifact path pattern! Edit the build artifacts again and make sure the following two artifact paths are specified:

build/release/*%system.build.number%*
unitTests/codeCoverage => coverage.zip

We can let TeamCity create a ZIP archive from the unitTests/codeCoverage path by simply using => and specifying a target artifact name.

Run the build again. Once it completes, the Artifacts tab should contain the coverage.zip file we've just created. Next to that, there should now be an additional tab Code Coverage available which displays code coverage results. Since we're using a TeamCity convention for reporting code coverage, namely creating a coverage.zip build artifact, TeamCity will automatically display the coverage results in a new report tab.

It's possible to add additional build reporting and display results from PHP mess detector, PHPLint or even have a tab available which displays phpDocumentor contents by creating custom report tabs based on information from build artifacts.