Clean up PHP CI example [ci skip]

1 files changed, 211 insertions, 114 deletions

diff --git a/doc/ci/languages/php.md b/doc/ci/languages/php.md
index e0589182003..c71ae40786e 100644
--- a/doc/ci/languages/php.md
+++ b/doc/ci/languages/php.md
@@ -1,178 +1,275 @@
-## Testing PHP projects
+# Testing PHP projects
 
-This guide covers basic of building PHP projects.
+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
-		curl -o /usr/local/bin/phpunit https://phar.phpunit.de/phpunit.phar
-		chmod +x /usr/local/bin/phpunit
+Let's create a `ci/docker_install.sh` file in the root directory of our
+repository with the following content:
 
-		# Install mysql driver
-		# Here you can install any other extension that you need
-		docker-php-ext-install pdo_mysql
+```bash
+#!/bin/bash
 
-3. From your `.gitlab-ci.yml` run the created script:
+# We need to install dependencies only for Docker
+[[ ! -e /.dockerinit ]] && exit 0
 
-		before_script:
-		- bash ci/docker_install.sh > /dev/null
+set -xe
 
-4. Now you can run your tests. Usually it will be `phpunit` with arguments:
+# Install git (the php image doesn't have it) which is required by composer
+apt-get update -yqq
+apt-get install git -yqq
 
-		test:app:
-		  script:
-		  - phpunit --configuration phpunit_myapp.xml --coverage-text
+# Install phpunit, the tool that we will use for testing
+curl -o /usr/local/bin/phpunit https://phar.phpunit.de/phpunit.phar
+chmod +x /usr/local/bin/phpunit
 
-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.
 
-		test:app:
-		  script:
-		  - phpunit --configuration phpunit_myapp.xml --coverage-text
+## Test PHP projects using the Shell executor
 
-#### Test against different PHP versions in Docker builds
+The shell executor runs your builds in a terminal session on your server.
+Thus, in order to test your projects you first need to make sure that all
+dependencies are installed.
 
-You can also test against multiple version of PHP runtime:
+For example, in a VM running Debian 8 we first update the cache, then we
+install `phpunit` and `php5-mysql`:
 
-		before_script:
-		# Install dependencies
-		- ci/docker_install.sh > /dev/null
+```bash
+sudo apt-get update -y
+sudo apt-get install -y phpunit php5-mysql
+```
 
-		# We test PHP5.6
-		test:5.6:
-		  image: php:5.6
-		  script:
-		  - phpunit --configuration phpunit_myapp.xml --coverage-text
+Next, add the following snippet to your `.gitlab-ci.yml`:
 
-		# We test PHP7.0
-		test:7.0:
-		  image: php:7.0
-		  script:
-		  - phpunit --configuration phpunit_myapp.xml --coverage-text
+```yaml
+test:app:
+  script:
+  - phpunit --configuration phpunit_myapp.xml
+```
 
-#### Custom PHP configuration in Docker builds
+Finally, push to GitLab and let the tests begin!
 
-You can customise your PHP environment by putting your .ini file into `/usr/local/etc/php/conf.d/`:
+### Test against different PHP versions in Shell builds
 
-		before_script:
-		- cp my_php.ini /usr/local/etc/php/conf.d/test.ini
+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:
+To install additional extensions simply execute:
 
-		test:app:
-		  script:
-		  - phpunit --configuration phpunit_myapp.xml --coverage-text
+```bash
+pecl install <extension>
+```
 
-#### Test against different PHP versions in Shell builds
+It's not advised to add this to `.gitlab-ci.yml`. You should execute this
+command once, only to setup the build environment.
 
-The [phpenv](https://github.com/phpenv/phpenv) allows you to easily manage different PHP with they own configs.
-This is specially usefull when testing PHP project with Shell executor.
+## Extend your tests
 
-Login as `gitlab-runner` user and follow [the installation guide](https://github.com/phpenv/phpenv#installation).
+### Using atoum
 
-Using phpenv also allows to easily configure PHP environment with: `phpenv config-add my_config.ini`.
+Instead of PHPUnit, you can use any other tool to run unit tests. For example
+you can use [atoum](https://github.com/atoum/atoum):
 
-#### Install custom extensions
+```yaml
+before_script:
+- wget http://downloads.atoum.org/nightly/mageekguy.atoum.phar
 
-Since we have pretty bare installation of our PHP environment you may need some extensions that are not present on your installation.
+test:atoum:
+  script:
+  - php mageekguy.atoum.phar
+```
 
-To install additional extensions simply execute.:
+### Using Composer
 
-		pecl install <extension>
+The majority of the PHP projects use Composer for managing their PHP packages.
+In order to execute Composer before running your tests, simply add the
+following in your `.gitlab-ci.yml`:
 
-	It's not advised to add this to the `.gitlab-ci.yml`.
-	You should execute this command once, only to setup the build environment.
+```yaml
+...
 
-### Extend your tests
+# Composer stores all downloaded packages in the vendor/ directory.
+# Do not use the following if the vendor/ directory is commited to
+# your git repository.
+cache:
+  paths:
+  - vendor/
 
-#### Using atoum
+before_script:
+# Install composer dependencies
+- curl -sS https://getcomposer.org/installer | php
+- php composer.phar install
 
-Instead of PHPUnit, you can use any other tool to run unit tests. For example [atoum](https://github.com/atoum/atoum):
+...
+```
 
-		before_script:
-		- wget http://downloads.atoum.org/nightly/mageekguy.atoum.phar
+## Access private packages / dependencies
 
-		test:atoum:
-		  script:
-		  - php mageekguy.atoum.phar
+If your test suite needs to access a private repository, you need to configure
+[the SSH keys](../ssh_keys/README.md) in order to be able to clone it.
 
-#### Using Composer
+## Use databases or other services
 
-Majority of the PHP projects use Composer for managing the packages.
-It's very simple to execute the Composer before running your tests.
-To your `.gitlab-ci.yml` add:
+Most of the time you will need a running database in order for your tests to
+run. If you are using the Docker executor you can leverage Docker's ability to
+connect to other containers. In GitLab Runner lingo, this can be achieved by
+defining a `service`.
 
-		# The composer stores all downloaded packages in vendor/
-		# Remove it if you committed the vendor/ directory
-		cache:
-		  paths:
-		  - vendor/
+This functionality is covered in [the CI services](../services/README.md)
+documentation.
 
-		before_script:
-		# Install composer dependencies
-		- curl -sS https://getcomposer.org/installer | php
-		- php composer.phar install
+## Testing things locally
 
-### Access private packages / dependencies
+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.
+[php-hub]: https://hub.docker.com/_/php/
+[phpenv]: https://github.com/phpenv/phpenv
+[phpenv-installation]: https://github.com/phpenv/phpenv#installation