Continuous Integration with PHP-CI

This article is written for and published on SitePoint.

Creating an application is one thing. Keeping it to a certain quality level is another thing entirely. These days, you can find many tools which can help you to keep the quality of your application in shape. Running these tools one by one can be very time consuming. For that, you can install so called continuous integration (CI) services. PHPCI is one of those and in this article, we will dive into it.

Continuous integration service

A continuous integration service is an application which runs certain quality check tools against your code. For example, a CI could pull in your git repository. When done, it runs unit tests, checks your code for validations and generates reports based on it. In general, a CI runs on certain time intervals or on every push. The most seen situation is right after creating a merge request. By checking the merge request, the code is checked before being merged, making sure you are not accepting code which could break functionality. So integrating CI within your development procedure can make sure bad code is kept out of your main repository and you can validate automatically if everything meets your requirements before accepting changes.

Installation

Installation can be done in two different ways. Either you download the latest release or you follow the installation guide. I decided to go with the installation guide and install it through Composer. After running composer update you can run the install script. You will be questioned for database credentials and your email address. When done, a user is created with the given email address.

You also need to set a cronjob so builds are run automatically.

Setup

Depending on what you want to do, you have to install some tools. After logging in, you can go to admin manage plugins and install any necessary plugins. By installing a plugin, you are updating the composer.json file with new requirements. So right after you installed the plugins you need to run composer update to actually install these plugins.

Add a project

By clicking the add project button in the header, you can create a new project. You have to fill in a simple form, which indicates were the code is located. You can choose between different kinds of services like Github and Bitbucket, but also for your own remote or local URLs. If you don’t have a phpci.yml configuration file within your repository, you need to provide the build configuration. Within his configuration, you define how the project needs to be set up, which tools you want to run and how to finalize the build.

Each build process consists of 5 phases.

1. Setup. The phase were everything is initialized
2. Test. The phase were all tests are executed
3. Complete. Success or failure, this part will always run
4. Success. Will only be run in case of success
5. Failure. Will only be run in case of failure

I will be using this project as our project. We want to ignore default directories like app and vendor. Installation will be done through Composer. The project should be PSR2 compliant, has unit tests and contains decent docblocks. We also want to check if the overall quality is fine by running PHPMD, PHPCPD and PHPLoc.

PHPCI is capable of handling a test database. However, the project we are using in our example does not have any functional tests, so we will leave out the MySQL connection.

Let’s take a look at what the configuration would look like.

build_settings:
    ignore:
        - "vendor"
        - "bin"
        - "app"

setup:
    composer:
        action: "install"

test:
    php_unit:
        config:
            - "app/phpunit.xml.dist"
        coverage: "coverage"
        args: "--stderr"
    php_mess_detector:
        allow_failures: true
    php_code_sniffer:
        standard: "PSR2"
    php_cpd:
        allow_failures: true
    php_docblock_checker:
        allowed_warnings: 10
        skip_classes: true
    php_loc:
        directory: "src"

After creating the project, you have to make sure that PHPCI is capable of retrieving the project from Github. In this case, I added the SSH key which PHPCI supplied me to my Github account. When done, you can click the build button to start building the project.

Build results

When the build is completed, the project will get a color matching the status on the overview page. You get a clear view of the previous build, the latest commit and the current branch. By clicking on the ID of a build, you can see the in depth results for the build.

Time to take a closer look on the results of a single build. On top of the page, you should be able to see two small graphs. One will indicate the lines of code while the other one will display the quality trend. The quality trend graph contains an overview of all the tools like PHPMD and PHPCPD.

Unfortunately, I was unable to get PHPLoc working correctly

Beneath the graphs, we can see in depth results per tool. For example we can have a look at the unit tests. In this case, I was aware of the fact that they should succeed. Within PHPCI, this was also the case. PHPCI indicates this, by leaving the table empty.

In case of a failure, PHPCI will clearly indicate what is wrong by retrieving feedback from the tool. In my case, PHPMD had some lines which they think could be improved. PHPCI shows me which file and what the message is. Next to that, I am able to click the file to go straight to my Github repository.

All the tools I used gave the same way feedback to me. Tables which are empty where successful, tables which were filled had some improvements.

Conclusion

Of course, PHPCI can do more than what was described above. If you are interested in all its features, have a look at their documentation. Basically, it can use any PHP QA tool you know.

So, what’s my final verdict? I have been using lots of tools in the past. A year ago, I was convinced that there was no single tool that could beat Jenkins. Till today, I still believe Jenkins is one of the best CI tools out there. Jenkins is capable of running all kinds of projects, not only PHP based ones. For me, that is a huge advantage when you are dealing with JS, iOS and Java applications. Jenkins is full featured, contains a lot of plugins and is capable of creating nice graphs about the quality of your project. It only lacks a nice and structured design and easy configuration.

I also love Travis in combination with Scrutinizer and SensioLabs Insight. Together they can give me a lot of feedback on my code and run all kinds of checks. However, if you are not working with open source projects, you have to pay for all three services to keep them running.

So, is PHPCI a nice addition in this line of tools? Yes, I believe so. They are really trying to target the PHP community and are offering one, single place, to run all kinds of checks. Next to that, it can produce already some graphs to give a quick overview of the quality of your project.

Don’t forget, PHPCI is not even a year old yet and that’s something you will notice. Installing a plugin requires you to run composer update, which means you still have to log in to your server. Also, the design sometimes is really off, especially when you are installing a package and you need to pick a version.

I would like to see some more helpful information on certain topics. It’s nice to know you have to fill in a configuration file, but if it could show you the possibilities or at least add a link to the documentation, that would help a lot. You might even wonder why the documentation is not integrated within the tool itself.

The most frustrating part for me was the fact that I received messages like Plugin Status: Success and Plugin Status: Failed in my console and the build was giving me an empty table.

I believed it meant that it somehow failed to run a tool like PHPUnit. Yet it tells you if PHPUnit actually succeeded or failed. A success also leads to an empty table, so you basically have no feedback in PHPCI itself. Would be nice if it just said something like “everything is ok…. moving on!” or at least gave me the results of PHPUnit.

Finally, it’s good to see the developers are also extending it with custom tools. For example, they created a docblock plugin. For now, I believe it only checks if a docblock is present or not. Would be nice if they could check all docblocks in the future to match the upcoming PSR-5 standard.

If you don’t want to set up Jenkins or you have a private project and you are only developing PHP projects, PHPCI could be the tool you are looking for. Personally I would wait a bit longer till they improved the design of the application before using it on a real project. It sometimes feels a bit clunky because the design is unclear or there is no correct description.