This guide covers basic building instructions for PHP projects.
Is it possible to test PHP apps on any system.
However, it will require manual configuration.
The simplest is to use Docker executor as described below.
There are covered two cases: testing using the Docker executor and testing
using the Shell executor.
### PHP projects on Docker executor
It's possible to official [PHP](https://hub.docker.com/_/php/) repositories on Docker Hub.
They allow to test PHP projects against different versions of the runtime.
However, they require additional configuration.
## Test PHP projects using the Docker executor
To build PHP project you need to create valid `.gitlab-ci.yml` describing the build environment:
1. First you need to specify PHP image as described here: http://doc.gitlab.com/ce/ci/docker/using_docker_images.html#what-is-image. To your `.gitlab-ci.yml` add:
While it is possible to test PHP apps on any system, this would require manual
configuration from the developer. To overcome this we will be using the
official [PHP docker image][php-hub] that can be found in Docker Hub.
image: php:5.6
This will allow us to test PHP projects against different versions of PHP.
However, not everything is plug 'n' play, you still need to onfigure some
things manually.
2. The official images are great, but they are lacking a few useful tools for testing. We need to install them first in build environment. Create `ci/docker_install.sh` file with following content:
As with every build, you need to create a valid `.gitlab-ci.yml` describing the
build environment.
#!/bin/bash
Let's first specify the PHP image that will be used for the build process
(you can read more about what an image means in the Runner's lingo reading
about [Using Docker images](../docker/using_docker_images.md#what-is-image)).
# We need to install dependencies only for Docker
[[ ! -e /.dockerinit ]] && exit 0
Start by adding the image to your `.gitlab-ci.yml`:
set -xe
```yaml
image:php:5.6
```
# Install git (the php image doesn't have it) which is required by composer
apt-get update -yqq
apt-get install git -yqq
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.
# Install phpunit, the tool that we will use for testing
5. Commit your files, and push them to GitLab to see if it works. With GitLab Runner 1.0 you can also test the changes locally. From your terminal execute:
# Install mysql driver
# Here you can install any other extension that you need
docker-php-ext-install pdo_mysql
```
# Check using docker executor
gitlab-runner exec docker test:app
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 easilly install
extensions. For more information read the the documentation at
<https://hub.docker.com/_/php/>.
# Check using shell executor
gitlab-runner exec shell test:app
Now that we created the script that contains all prerequisites for our build
environment, let's add it in `.gitlab-ci.yml`:
```yaml
...
before_script:
-bash ci/docker_install.sh > /dev/null
...
```
Last step, run the actual tests using `phpunit`:
```yaml
...
test:app:
script:
-phpunit --configuration phpunit_myapp.xml
...
```
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:
# Select image from https://hub.docker.com/_/php/
image: php:5.6
```yaml
# Select image from https://hub.docker.com/_/php/
image:php:5.6
before_script:
# Install dependencies
-ci/docker_install.sh > /dev/null
test:app:
script:
-phpunit --configuration phpunit_myapp.xml
```
### 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 will do the rest:
```yaml
before_script:
# Install dependencies
-ci/docker_install.sh > /dev/null
# We test PHP5.6
test:5.6:
image:php:5.6
script:
-phpunit --configuration phpunit_myapp.xml
# We test PHP7.0 (good luck with that)
test:7.0:
image:php:7.0
script:
-phpunit --configuration phpunit_myapp.xml
```
### Custom PHP configuration in Docker builds
There are times where you will 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:
```yaml
before_script:
-cp my_php.ini /usr/local/etc/php/conf.d/test.ini
```
before_script:
# Install dependencies
- ci/docker_install.sh > /dev/null
Of course, `my_php.ini` must be present in the root directory of your repository.
The [phpenv][] project allows you to easily manage different versions of PHP
each with its own config. This is specially usefull when testing PHP projects
with the Shell executor.
### Test PHP projects using Shell
You will have to install it on your build machine under the `gitlab-runner`
user following [the upstream installation guide][phpenv-installation].
Shell executor runs your builds in terminal session of your server. Thus in order to test your projects you need to have all dependencies installed as root.
Using phpenv also allows to easily configure the PHP environment with:
1. Install PHP dependencies:
```
phpenv config-add my_config.ini
```
sudo apt-get update -qy
sudo apt-get install phpunit php5-mysql -y
### Install custom extensions
This will install the PHP version available for your distribution.
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.
2. Now you can run your tests. Usually it will be `phpunit` with arguments:
With GitLab Runner 1.0 you can also test any changes locally. From your
terminal execute:
You need to configure [the SSH keys](../ssh_keys/README.md) in order to checkout the repositories.
```bash
# Check using docker executor
gitlab-runner exec docker test:app
### Use databases or other services
# Check using shell executor
gitlab-runner exec shell test:app
```
Please checkout the docs about configuring [the CI services](../services/README.md).
## Example project
### Example project
We have set up an [Example PHP Project](https://gitlab.com/gitlab-examples/php)
for your convenience that runs on [GitLab.com](https://gitlab.com) using our
publicly available [shared runners](../runners/README.md).
You maybe interested in our [Example Project](https://gitlab.com/gitlab-examples/php) that runs on [GitLab.com](https://gitlab.com) using our publically available shared runners.
Want to hack it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin.
Want to hack it? Simply fork it, commit and push changes. Within a few moments the changes will be picked and rebuilt by public runners.
