CI and Version Control

Version control is essential for CI. A CI system needs to acquire the most recent version of a project without human intervention (at least once things have been set up).

For this example, I’ll use a repository I set up on BitBucket. I’ll configure code on my local development machine, add and commit it, and then push to the remote server:

$ cd path/to/userthing                    
$ git init                    
$ git remote add origin git@bitbucket.org:getinstance/userthing.git                    
$ git add build.xml composer.json src/ test/                    
$ git commit -m 'initial commit'                    
$ git push -u origin master                    

I navigated to my development directory and initialized it. Then I added the origin remote, to which I pushed the code. I like to confirm that everything is working by performing a fresh clone:

$ git clone git@bitbucket.org:getinstance/userthing.git                    
Cloning into 'userthing'...
X11 forwarding request failed on channel 0
remote: Counting objects: 16, done.
remote: Compressing objects: 100% (11/11), done.
remote: Total 16 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (16/16), done.

Checking connectivity… done. Now I have a userthing repository and a local clone.Time to automate build and test.

Phing

We encountered Phing in Chapter 19. Here is one way to install the tool:

$ sudo pear channel-discover pear.phing.info                    
$ sudo pear install phing/phing                    

I’ll use Composer for this, however. Here’s the require-dev directive in my composer.json file:

    "require-dev": {
        "phing/phing": "2.*"
    }

I will be using this essential build tool as the glue for my project’s CI environment, so I run this install on the server I intend to use for testing (or, of course, you could try this out on virtual server using Vagrant and VirtualBox). I will define targets for building and testing the code and for running the various other quality assurance tools you will meet in this chapter.

Let’s build a sample task:

<project name="userthing" default="build" basedir=".">
    <property name="build" value="./build" />
    <property name="test" value="./test" />
    <property name="src" value="./src" />
    <property name="version" value="1.1.1" />

    <target name="build">
        <mkdir dir="${build}" />
        <copy todir="${build}/src">
            <fileset dir="${src}">
            </fileset>
        </copy>

        <copy todir="${build}/test">
            <fileset dir="${test}">
            </fileset>
        </copy>

    </target>

    <target name="clean">
        <delete dir="${build}" />
    </target>
    <!-- ... -->  
</project>

I set up four properties. build refers to the directory in which I might assemble my files before generating a package. test points to the test directory. src refers to the source directory. version defines the version number for the package.

The build target copies the src and test directories into the build environment. In a more complex project, I might also perform transformations, generate configuration files, and assemble binary assets at this stage. This target is the project’s default.

The clean target removes the build directory and anything it contains. Let’s run a build:

$ vendor/bin/phing                      
Buildfile: /var/popp/src/ch21/build.xml

userthing > build:

    [mkdir] Created dir: /var/popp/src/ch21/build
     [copy] Created 4 empty directories in /var/popp/src/ch21/build/src
     [copy] Copying 3 files to /var/popp/src/ch21/build/src
     [copy] Created 3 empty directories in /var/popp/src/ch21/build/test
     [copy] Copying 2 files to /var/popp/src/ch21/build/test

BUILD FINISHED

Total time: 1.8206 second

Unit Tests

Unit tests are the key to continuous integration. It’s no good successfully building a project that contains broken code. I covered unit testing with PHPUnit in Chapter 18. If you’re reading out of order, however, you’ll want to install this invaluable tool before proceeding. Here is one way to install PHPUnit globally:

$ wget https://phar.phpunit.de/phpunit.phar                    
$ chmod 755 phpunit.phar                    
$ sudo mv phpunit.phar /usr/local/bin/phpunit                    

You can also install PHPUnit with Composer:

    "require-dev": {
        "phing/phing": "2.*",
         "phpunit/phpunit": "5.4.*"
    }

Again, this is the approach I’ll take for my example. Because PHPUnit will be installed under the vendor/ directory, my development directory will remain independent of the wider system.

I’ve separated my test directory from the rest of my source code, so I’ll need to set up my autoload rules so that PHP can locate all the system’s classes during testing. Here’s my complete composer.json:

{
    "require-dev": {
        "phing/phing": "2.*",
         "phpunit/phpunit": "5.4.*"
    },
    "autoload": {
        "psr-4": {
            "userthing\\": ["src/", "test/"]
        }
    }

Also in Chapter 18, I wrote tests for a version of the userthing code I’ll be working with in this chapter. Here I run them once again (from within the src directory), to make sure my reorganization has not broken anything new:

$ vendor/bin/phpunit test/                      
PHPUnit 5.4.6 by Sebastian Bergmann and contributors.

...... 6 / 6 (100%)

Time: 378 ms, Memory: 4.00MB

OK (6 tests, 5 assertions)

So this confirms that my tests work. However, I would like to invoke them with Phing.

Phing provides an exec task which we might use to invoke the phpunit command. However, it’s always best to use a specialized tool if there’s one available. There is a built-in task for this job:

    <target name="test" depends="build">
        <phpunit bootstrap="vendor/autoload.php" printsummary="true">
            <formatter type="plain" usefile="false"/>
            <batchtest>
                <fileset dir="${test}">
                    <include name="**/*Test.php"/>
                </fileset>
            </batchtest>
        </phpunit>
    </target>

Because these are unit tests and not functional tests, we can run them against the local src/ directory rather than requiring an installed instance (with a functioning database or web server). Among many other attributes, the phpunit task accepts a printsummary attribute, which causes an overview of the test process to be output.

Much of this task’s functionality is configured using nested elements. The formatter element manages the way that test information is generated. In this case, I have opted to output basic human-readable data. batchtest lets you define multiple test files using the nested fileset element.

Here, I run the tests with Phing:

$ vendor/bin/phing test                      
Buildfile: /var/poppch21/build.xml

userthing > build:

userthing > test:

  [phpunit] Testsuite: userthing\persist\UserStoreTest
  [phpunit] Tests run: 4, Failures: 0, Errors: 0, Incomplete: 0, Skipped: 0, Time elapsed: 0.01105 s
  [phpunit] Testsuite: userthing\util\ValidatorTest
  [phpunit] Tests run: 2, Failures: 0, Errors: 0, Incomplete: 0, Skipped: 0, Time elapsed: 0.00864 s
  [phpunit] Total tests run: 6, Failures: 0, Errors: 0, Incomplete: 0, Skipped: 0, Time elapsed: 0.02641 s

BUILD FINISHED

Total time: 0.5815 seconds

BUILD FINISHED

Total time: 1.0921 second

Documentation

Transparency is one of the principles of CI. When you’re looking at a build in a Continuous Integration environment, therefore, it’s important to be able to check that the documentation is up-to-date, and covers the most recent classes and methods. You can install phpDocumentor with PEAR like this:

$ pear channel-discover pear.phpdoc.org                    
$ pear install phpdoc/phpdocumentor                    

Or, once again, you can use Composer:

    "require-dev": {
        "phing/phing": "2.*",
        "phpunit/phpunit": "5.4.*",
        "phpdocumentor/phpdocumentor": "2.*"
    }

I’d better invoke the tool just to be sure, this time from the build directory:

$ ./vendor/bin/phpdoc --directory=src --target=docs --title=userthing                    

This generates some pretty bare documentation. Once it’s published on a CI server, I’m sure to be shamed into writing some real inline documentation.

Once again, I want to add this to my build.xml document. There is a task named phpdoc2 that is designed to integrate with PHPDocumentor:

    <target name="doc" depends="build">
        <mkdir dir="reports/docs" />
        <phpdoc2 title="API Documentation" destdir="reports/docs">
           <fileset dir="${src}">
              <include name="**/*.php" />
           </fileset>
        </phpdoc2>
    </target>

Again, my doc target depends upon the build target. I create the reports/docs output directory, and then invoke the phpdoc2 task. phpdoc2 accepts a nested fileset element, which specifies the files to document.

Code Coverage

It’s no good relying on tests if they don’t apply to the code you have written. PHPUnit includes the ability to report on code coverage . Here’s an extract from PHPUnit’s usage information:

  --coverage-html <dir>    Generate code coverage report in HTML format.
  --coverage-clover <file> Write code coverage data in Clover XML format.

In order to use this feature, you must have the Xdebug extension installed. You can find more about this at http://pecl.php.net/package/Xdebug (installation information is at http://xdebug.org/docs/install ). You may also be able to install directly using your Linux distribution’s package-management system. This should work for you in Fedora, for example:

$ yum install php-pecl-xdebug                    

Or, if you’re using a version-specific repository, you might do something like this:

$ sudo yum -y install php70w-pecl-xdebug                    

Here I run PHPUnit from the src/ directory with code coverage enabled:

$ ./vendor/bin/phpunit --whitelist src/ --coverage-html coverage test                      
PHPUnit 5.4.6 by Sebastian Bergmann and contributors.

......                                                              6 / 6 (100%)

Time: 1.84 seconds, Memory: 6.00MB

OK (6 tests, 5 assertions)

Generating code coverage report in HTML format ... done

Now you can see the report in your browser (see Figure 21-1).

Figure 21-1. The code coverage report

It’s important to note that achieving full coverage is not the same as adequately testing a system. On the other hand, it’s good to know about any gaps in your tests. As you can see from Figure 21-2, I’ve still got some work to do.

Figure 21-2. The install screen

Having confirmed that I can check coverage from the command line, I need to add this functionality to my build document:

    <target name="citest" depends="build">
        <mkdir dir="reports/coverage" />

        <coverage-setup database="reports/coverage.db">
            <fileset dir="${src}">
                <include name="**/*.php"/>
            </fileset>
        </coverage-setup>

        <phpunit codecoverage="true" bootstrap="vendor/autoload.php" printsummary="true">
            <formatter type="plain" usefile="false"/>
            <formatter type="xml" outfile="testreport.xml" todir="reports" />
            <formatter type="clover" outfile="cloverreport.xml" todir="reports" />
            <batchtest>
                <fileset dir="${test}">
                    <include name="**/*Test.php"/>
                </fileset>
            </batchtest>
        </phpunit>

        <coverage-report outfile="reports/coverage.xml">
           <report todir="reports/coverage" />
        </coverage-report>
    </target>

I have created a new task named citest. Much of it is a reproduction of the test task you have already seen.

I start by creating a reports directory and a coverage subdirectory.

I use the coverage-setup task to provide configuration information for the coverage feature. I specify where raw coverage data should be stored using the database attribute. The nested fileset element defines the files that should be subject to coverage analysis.

I have added two formatter elements to the phpunit task. The formatter of type xmlwill generate a file named testreport.xml, which will contain the test results. The clover formatter will generate coverage information, also in XML format. Finally, in the citest target, I deploy the coverage-report task. This takes existing coverage information, generates a new XML file, and then outputs an HTML report.

Coding Standards

I discussed coding standards at length in Chapter 16. Although it can be annoying to have your individual style cramped by a shared standard, it can make a project easier to work with for the wider team. For that reason, many teams enforce a standard. It’s hard to enforce this by eye, however, so it makes sense to automate the process.

Once again, I will use Composer. This time I’ll be configuring it to install PHP_CodeSniffer :

    "require-dev": {
        "phing/phing": "2.*",
        "phpunit/phpunit": "5.4.*",
        "phpdocumentor/phpdocumentor": "2.*",
        "squizlabs/php_codesniffer": "2.*"
    }

Now I will apply the PSR2 coding standard to my code:

$ vendor/bin/phpcs—standard=PSR2 src/util/Validator.php                      
FILE: /var/poppch21/src/util/Validator.php
----------------------------------------------------------------------
FOUND 6 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------
  8 | ERROR | [x] Opening brace of a class must be on the line after
    |       |     the definition
 11 | ERROR | [ ] Visibility must be declared on method "__construct"
 11 | ERROR | [x] Opening brace should be on a new line
 15 | ERROR | [ ] Visibility must be declared on method
    |       |     "validateUser"
 15 | ERROR | [x] Opening brace should be on a new line
 26 | ERROR | [x] Function closing brace must go on the next line
    |       |     following the body; found 1 blank lines before
    |       |     brace
----------------------------------------------------------------------
PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

Time: 358ms; Memory: 4Mb

Clearly, I need to clean up my code a little!

One benefit of an automated tool is its impersonal nature. If your team does decide to impose a set of coding conventions, it’s arguably better having a humorless script correcting your style than a humorless coworker doing the same thing.

As you might expect by now, I would like to add a CodeSniffer target to my build file:

    <target name="sniff" depends="build">
        <phpcodesniffer standard="PSR2">
            <fileset dir="src">
                <include name="**/*.php"/>
            </fileset>
            <formatter type="checkstyle" outfile="reports/checkstyle.xml"/>
        </phpcodesniffer>
    </target>

The phpcodesniffer task will do this job for me. I use the standard attribute to specify PSR2 rules. I define the files to check using the nested fileset element. I define a formatter element with a checkstyle type attribute. This will generate an XML file in the reports directory.

So I have a lot of useful tools that I can use to monitor my project. Of course, left to myself I’d soon lose interest in running them, even with my useful Phing build file. In fact, I’d probably revert to the old idea of an integration phase, and pull out the tools only when I’m close to a release, by which time their effectiveness as early-warning systems will be irrelevant. What I need is a CI server to run the tools for me.

Jenkins (formerly named Hudson) is an open source-continuous integration server. Although it is written in Java, Jenkins is easy to use with PHP tools. That’s because the continuous-integration server stands outside of the projects it builds, kicking off and monitoring the results of various commands. Jenkins also integrates well with PHP because it is designed to support plug-ins, and there is a highly active developer community working to extend the server’s core functionality.

Installing Jenkins

Jenkins is a Java system, so you will need to have Java installed. How you go about this will vary from system to system. On a Fedora distribution you might do something like this:

$ yum install java-1.7.0                    

Otherwise, you can get Java directly from www.java.com .

You can confirm that you have Java by running it from the command line:

$ java -version                    
java version "1.7.0_101"
OpenJDK Runtime Environment (rhel-2.6.6.4.el6_8-x86_64 u101-b00)
OpenJDK 64-Bit Server VM (build 24.95-b01, mixed mode)

You can get Jenkins from the project homepage at http://jenkins-ci.org/ . It can be installed via a Java Web Archive (WAR) file, or there are native packages for most distributions, all linked from the homepage. I will use the Fedora option:

$ wget -O /etc/yum.repos.d/jenkins.repo http://pkg.jenkins-ci.org/redhat/jenkins.repo                    
$ rpm --import http://pkg.jenkins-ci.org/redhat/jenkins-ci.org.key                    
$ yum install jenkins                    

The Jenkins site provides installation instructions for most distributions.

Once Jenkins is installed you could run it directly via Java like this:

$ sudo java -jar /usr/lib/jenkins/jenkins.war                    

However, you may run in to trouble later on if you do this. It’s almost certainly better to use a startup script, which will run Jenkins as the jenkins user. In the case of Fedora, you can start Jenkins like this:

$ service jenkins start                    

You can also find a generic startup script at https://wiki.jenkins-ci.org/display/JENKINS/JenkinsLinuxStartupScript .

By default, Jenkins runs on port 8080, so you can find out whether you’re ready to proceed by firing up your browser and visiting http://yourhost:8080/. You should see something like the screen in Figure 21-2.

The instructions in Figure 21-2 are pretty self-explanatory. I grab the password from /var/lib/jenkins/secrets/initialAdminPassword and enter it into the box provided. Then I’m presented with a choice: install with popular plug-ins or pick my own? I opt for the most popular plug-ins, which I know will get me support for Git among other things. If you want a slim system, you might choose to select only those plug-ins you need. After that it’s time to create a user name and password before finishing up installation.

Test Failures

So far everything seems to be going well, even if userthing won’t be winning any code-compliance badges any time soon. But tests succeed when they fail, so I’d better break something to make sure that Jenkins reports on it.

Here is a part of a class named Validate in the namespace userthing\util:

    public function validateUser(string $mail, string $pass): boolean
    {
        // make it always fail                
        return false;                
        $user = $this->store->getUser($mail);
        if (is_null($user)) {
            return null;
        }
        if ($user->getPass() == $pass) {
            return true;
        }

        $this->store->notifyPasswordFailure($mail);

        return false;
    }

See how I’ve sabotaged the method? As it now stands, validateUser()will always return false.

Here’s the test that should choke on that. It’s in test/util/ValidatorTest.php:

    public function testValidateCorrectPass()
    {
        $this->assertTrue(
            $this->validator->validateUser("bob@example.com", "12345"),
            "Expecting successful validation"
        );
    }

Having made my change, all I need do is commit, and wait. Sure enough, before long, the project status shows a build marked by a yellow icon. Once I click on the build link, I find more details. You can see the screen in Figure 21-13.

Figure 21-13. The Unstable Build