Testing PHP projects – GitLab Documentation

  • Test PHP projects using the Docker executor
    • Test against different PHP versions in Docker builds
    • Custom PHP configuration in Docker builds
  • Test PHP projects using the Shell executor
    • Test against different PHP versions in Shell builds
    • Install custom extensions
  • Extend your tests
    • Using atoum
    • Using Composer
  • Access private packages or dependencies
  • Use databases or other services
  • Testing things locally
  • Example project

This guide covers basic building instructions for PHP projects.

Two testing scenarios are covered: using the Docker executor and using the Shell executor.

Test PHP projects using the Docker executor

While it is possible to test PHP apps on any system, this would require manual configuration from the developer. To overcome this we use the official PHP Docker image that can be found in Docker Hub.

This allows us to test PHP projects against different versions of PHP. However, not everything is plug ‘n’ play, you still need to configure some things manually.

As with every job, you need to create a valid .gitlab-ci.yml describing the build environment.

READ:  What to Consider When Migrating to Another Web Hosting Provider

Let’s first specify the PHP image that is used for the job process. (You can read more about what an image means in the runner’s lingo reading about Using Docker images.)

Start by adding the image to your .gitlab-ci.yml:

The official images are great, but they lack a few useful tools for testing. We need to first prepare the build environment. A way to overcome this is to create a script which installs all prerequisites prior the actual testing is done.

Let’s create a ci/docker_install.sh file in the root directory of our repository with the following content:

You might wonder what docker-php-ext-install is. In short, it is a script provided by the official PHP Docker image that you can use to easily install extensions. For more information read the documentation.

Now that we created the script that contains all prerequisites for our build environment, let’s add it in .gitlab-ci.yml:

Last step, run the actual tests using phpunit:

Finally, commit your files and push them to GitLab to see your build succeeding (or failing).

The final .gitlab-ci.yml should look similar to this:

Test against different PHP versions in Docker builds

Testing against multiple versions of PHP is super easy. Just add another job with a different Docker image version and the runner does the rest:

Custom PHP configuration in Docker builds

There are times where you need to customise your PHP environment by putting your .ini file into /usr/local/etc/php/conf.d/. For that purpose add a before_script action:

READ:  WordPress Blog Hosting - How to Pick a Host and What to Look For

Of course, my_php.ini must be present in the root directory of your repository.

Test PHP projects using the Shell executor

The shell executor runs your job in a terminal session on your server. To test your projects, you must first ensure that all dependencies are installed.

For example, in a VM running Debian 8, first update the cache, and then install phpunit and php5-mysql:

Next, add the following snippet to your .gitlab-ci.yml:

Finally, push to GitLab and let the tests begin!

Test against different PHP versions in Shell builds

The phpenv project allows you to easily manage different versions of PHP each with its own configuration. This is especially useful when testing PHP projects with the Shell executor.

You have to install it on your build machine under the gitlab-runner user following the upstream installation guide.

Using phpenv also allows to easily configure the PHP environment with:

Important note: It seems phpenv/phpenv is abandoned. There is a fork at madumlao/phpenv that tries to bring the project back to life. CHH/phpenv also seems like a good alternative. Picking any of the mentioned tools works with the basic phpenv commands. Guiding you to choose the right phpenv is out of the scope of this tutorial.*

Install custom extensions

Since this is a pretty bare installation of the PHP environment, you may need some extensions that are not currently present on the build machine.

READ:  What is the Difference Between Linux and Windows Hosting?

To install additional extensions, execute:

It’s not advised to add this to .gitlab-ci.yml. You should execute this command once, only to set up the build environment.

Extend your tests

Using atoum

Instead of PHPUnit, you can use any other tool to run unit tests. For example you can use atoum:

Using Composer

The majority of the PHP projects use Composer for managing their PHP packages. To execute Composer before running your tests, add the following to your .gitlab-ci.yml:

Access private packages or dependencies

If your test suite needs to access a private repository, you need to configure the SSH keys to be able to clone it.

Use databases or other services

Most of the time, you need a running database for your tests to be able to run. If you’re using the Docker executor, you can leverage Docker’s ability to link to other containers. With GitLab Runner, this can be achieved by defining a service.

This functionality is covered in the CI services documentation.

Testing things locally

With GitLab Runner 1.0 you can also test any changes locally. From your terminal execute:

Example project

We have set up an Example PHP Project for your convenience that runs on GitLab.com using our publicly available shared runners.

Want to hack on it? Fork it, commit, and push your changes. Within a few moments the changes are picked by a public runner and the job begins.