debian-mirror-gitlab/doc/ci/examples/php.md

277 lines
8.3 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2020-06-23 00:09:42 +05:30
stage: Verify
group: Continuous Integration
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-09-04 21:01:54 +05:30
type: tutorial
---
2015-12-23 02:04:40 +05:30
# Testing PHP projects
This guide covers basic building instructions for PHP projects.
2019-09-30 21:07:59 +05:30
Two testing scenarios are covered: using the Docker executor and
2015-12-23 02:04:40 +05:30
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
2021-02-22 17:27:13 +05:30
configuration from the developer. To overcome this we use the
2020-06-23 00:09:42 +05:30
official [PHP Docker image](https://hub.docker.com/_/php) that can be found in Docker Hub.
2015-12-23 02:04:40 +05:30
2021-02-22 17:27:13 +05:30
This allows us to test PHP projects against different versions of PHP.
2016-04-02 18:10:28 +05:30
However, not everything is plug 'n' play, you still need to configure some
2015-12-23 02:04:40 +05:30
things manually.
2017-08-17 22:00:37 +05:30
As with every job, you need to create a valid `.gitlab-ci.yml` describing the
2015-12-23 02:04:40 +05:30
build environment.
2021-02-22 17:27:13 +05:30
Let's first specify the PHP image that is used for the job process
2020-11-24 15:15:51 +05:30
(you can read more about what an image means in the runner's lingo reading
2018-12-13 13:39:08 +05:30
about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)).
2015-12-23 02:04:40 +05:30
Start by adding the image to your `.gitlab-ci.yml`:
```yaml
image: php:5.6
```
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:
2020-03-13 15:44:24 +05:30
```shell
2015-12-23 02:04:40 +05:30
#!/bin/bash
# We need to install dependencies only for Docker
2017-08-17 22:00:37 +05:30
[[ ! -e /.dockerenv ]] && exit 0
2015-12-23 02:04:40 +05:30
set -xe
# Install git (the php image doesn't have it) which is required by composer
apt-get update -yqq
apt-get install git -yqq
# Install phpunit, the tool that we will use for testing
2021-02-22 17:27:13 +05:30
curl --location --output /usr/local/bin/phpunit "https://phar.phpunit.de/phpunit.phar"
2015-12-23 02:04:40 +05:30
chmod +x /usr/local/bin/phpunit
# Install mysql driver
# Here you can install any other extension that you need
docker-php-ext-install pdo_mysql
```
You might wonder what `docker-php-ext-install` is. In short, it is a script
2020-06-23 00:09:42 +05:30
provided by the official PHP Docker image that you can use to easily install
2021-03-11 19:13:27 +05:30
extensions. For more information read [the documentation](https://hub.docker.com/_/php).
2015-12-23 02:04:40 +05:30
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:
2020-07-28 23:09:34 +05:30
- bash ci/docker_install.sh > /dev/null
2015-12-23 02:04:40 +05:30
```
Last step, run the actual tests using `phpunit`:
```yaml
test:app:
script:
2020-07-28 23:09:34 +05:30
- phpunit --configuration phpunit_myapp.xml
2015-12-23 02:04:40 +05:30
```
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:
```yaml
2019-09-30 21:07:59 +05:30
# Select image from https://hub.docker.com/_/php
2015-12-23 02:04:40 +05:30
image: php:5.6
before_script:
2020-11-24 15:15:51 +05:30
# Install dependencies
2020-07-28 23:09:34 +05:30
- bash ci/docker_install.sh > /dev/null
2015-12-23 02:04:40 +05:30
test:app:
script:
2020-07-28 23:09:34 +05:30
- phpunit --configuration phpunit_myapp.xml
2015-12-23 02:04:40 +05:30
```
### Test against different PHP versions in Docker builds
Testing against multiple versions of PHP is super easy. Just add another job
2021-02-22 17:27:13 +05:30
with a different Docker image version and the runner does the rest:
2015-12-23 02:04:40 +05:30
```yaml
before_script:
2020-11-24 15:15:51 +05:30
# Install dependencies
2020-07-28 23:09:34 +05:30
- bash ci/docker_install.sh > /dev/null
2015-12-23 02:04:40 +05:30
# We test PHP5.6
test:5.6:
image: php:5.6
script:
2020-07-28 23:09:34 +05:30
- phpunit --configuration phpunit_myapp.xml
2015-12-23 02:04:40 +05:30
# We test PHP7.0 (good luck with that)
test:7.0:
image: php:7.0
script:
2020-07-28 23:09:34 +05:30
- phpunit --configuration phpunit_myapp.xml
2015-12-23 02:04:40 +05:30
```
### Custom PHP configuration in Docker builds
2021-02-22 17:27:13 +05:30
There are times where you need to customise your PHP environment by
2015-12-23 02:04:40 +05:30
putting your `.ini` file into `/usr/local/etc/php/conf.d/`. For that purpose
add a `before_script` action:
```yaml
before_script:
2020-07-28 23:09:34 +05:30
- cp my_php.ini /usr/local/etc/php/conf.d/test.ini
2015-12-23 02:04:40 +05:30
```
Of course, `my_php.ini` must be present in the root directory of your repository.
## Test PHP projects using the Shell executor
2021-01-03 14:25:43 +05:30
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.
2015-12-23 02:04:40 +05:30
2021-01-03 14:25:43 +05:30
For example, in a VM running Debian 8, first update the cache, and then install
`phpunit` and `php5-mysql`:
2015-12-23 02:04:40 +05:30
2020-03-13 15:44:24 +05:30
```shell
2015-12-23 02:04:40 +05:30
sudo apt-get update -y
sudo apt-get install -y phpunit php5-mysql
```
Next, add the following snippet to your `.gitlab-ci.yml`:
```yaml
test:app:
script:
2020-07-28 23:09:34 +05:30
- phpunit --configuration phpunit_myapp.xml
2015-12-23 02:04:40 +05:30
```
Finally, push to GitLab and let the tests begin!
### Test against different PHP versions in Shell builds
2020-04-22 19:07:51 +05:30
The [phpenv](https://github.com/phpenv/phpenv) project allows you to easily manage different versions of PHP
2020-06-23 00:09:42 +05:30
each with its own configuration. This is especially useful when testing PHP projects
2015-12-23 02:04:40 +05:30
with the Shell executor.
2021-02-22 17:27:13 +05:30
You have to install it on your build machine under the `gitlab-runner`
2020-04-22 19:07:51 +05:30
user following [the upstream installation guide](https://github.com/phpenv/phpenv#installation).
2015-12-23 02:04:40 +05:30
Using phpenv also allows to easily configure the PHP environment with:
2020-03-13 15:44:24 +05:30
```shell
2015-12-23 02:04:40 +05:30
phpenv config-add my_config.ini
```
*__Important note:__ It seems `phpenv/phpenv`
[is abandoned](https://github.com/phpenv/phpenv/issues/57). There is a fork
2021-03-11 19:13:27 +05:30
at [`madumlao/phpenv`](https://github.com/madumlao/phpenv) that tries to bring
the project back to life. [`CHH/phpenv`](https://github.com/CHH/phpenv) also
2021-02-22 17:27:13 +05:30
seems like a good alternative. Picking any of the mentioned tools works
2015-12-23 02:04:40 +05:30
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.
To install additional extensions simply execute:
2020-03-13 15:44:24 +05:30
```shell
2015-12-23 02:04:40 +05:30
pecl install <extension>
```
It's not advised to add this to `.gitlab-ci.yml`. You should execute this
2018-12-05 23:21:45 +05:30
command once, only to set up the build environment.
2015-12-23 02:04:40 +05:30
## Extend your tests
2021-03-11 19:13:27 +05:30
### Using `atoum`
2015-12-23 02:04:40 +05:30
Instead of PHPUnit, you can use any other tool to run unit tests. For example
2021-03-11 19:13:27 +05:30
you can use [`atoum`](https://github.com/atoum/atoum):
2015-12-23 02:04:40 +05:30
```yaml
before_script:
2020-07-28 23:09:34 +05:30
- wget http://downloads.atoum.org/nightly/mageekguy.atoum.phar
2015-12-23 02:04:40 +05:30
test:atoum:
script:
2020-07-28 23:09:34 +05:30
- php mageekguy.atoum.phar
2015-12-23 02:04:40 +05:30
```
### Using Composer
The majority of the PHP projects use Composer for managing their PHP packages.
2021-01-03 14:25:43 +05:30
To execute Composer before running your tests, add the following to your
`.gitlab-ci.yml`:
2015-12-23 02:04:40 +05:30
```yaml
# Composer stores all downloaded packages in the vendor/ directory.
2018-03-17 18:26:18 +05:30
# Do not use the following if the vendor/ directory is committed to
2015-12-23 02:04:40 +05:30
# your git repository.
cache:
paths:
2020-07-28 23:09:34 +05:30
- vendor/
2015-12-23 02:04:40 +05:30
before_script:
2020-11-24 15:15:51 +05:30
# Install composer dependencies
2020-07-28 23:09:34 +05:30
- wget https://composer.github.io/installer.sig -O - -q | tr -d '\n' > installer.sig
- php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
- php -r "if (hash_file('SHA384', 'composer-setup.php') === file_get_contents('installer.sig')) { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
- php composer-setup.php
- php -r "unlink('composer-setup.php'); unlink('installer.sig');"
- php composer.phar install
2015-12-23 02:04:40 +05:30
```
2019-09-04 21:01:54 +05:30
## Access private packages or dependencies
2015-12-23 02:04:40 +05:30
If your test suite needs to access a private repository, you need to configure
2021-03-11 19:13:27 +05:30
the [SSH keys](../ssh_keys/index.md) to be able to clone it.
2015-12-23 02:04:40 +05:30
## Use databases or other services
2021-01-03 14:25:43 +05:30
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`.
2015-12-23 02:04:40 +05:30
2021-03-11 19:13:27 +05:30
This functionality is covered in [the CI services](../services/index.md)
2015-12-23 02:04:40 +05:30
documentation.
## Testing things locally
With GitLab Runner 1.0 you can also test any changes locally. From your
terminal execute:
2020-03-13 15:44:24 +05:30
```shell
2015-12-23 02:04:40 +05:30
# Check using docker executor
2018-03-17 18:26:18 +05:30
gitlab-runner exec docker test:app
2015-12-23 02:04:40 +05:30
# Check using shell executor
2018-03-17 18:26:18 +05:30
gitlab-runner exec shell test:app
2015-12-23 02:04:40 +05:30
```
## Example project
2020-04-22 19:07:51 +05:30
We have set up an [Example PHP Project](https://gitlab.com/gitlab-examples/php) for your convenience
2015-12-23 02:04:40 +05:30
that runs on [GitLab.com](https://gitlab.com) using our publicly available
[shared runners](../runners/README.md).
2019-09-04 21:01:54 +05:30
Want to hack on it? Simply fork it, commit, and push your changes. Within a few
2021-02-22 17:27:13 +05:30
moments the changes are picked by a public runner and the job begins.