Running PHP with Docker

As a developer who works on multiple projects you often need different PHP versions for running tests or installing Composer packages.

I created a little Bash script that runs Docker for executing PHP in your project context. The script looks like this (don’t be scared, I will walk you through it step by step):

#!/usr/bin/env bash

phpVersion=7.2
remainingArguments="$@"

if [[ "$1" =~ (5.6|7.0|7.1|7.2|7.3) ]]; then
    phpVersion=$1
    remainingArguments="${@:2}"
fi

echo "Using PHP version $phpVersion"

docker run  --interactive --rm --tty \
    --user $(id -u):$(id -g) \
    -v ${HOME}/.ssh:${HOME}/.ssh:rw \
    -v ${SSH_AUTH_SOCK}:/ssh-auth.sock \
    --env SSH_AUTH_SOCK=/ssh-auth.sock \
    -v /etc/passwd:/etc/passwd:ro \
    -v /etc/passwd:/etc/group:ro \
    -v ${HOME}/.config/composer:${HOME}/.config/composer:rw \
    -v ${HOME}/.cache/composer:${HOME}/.cache/composer:rw \
    --env COMPOSER_CACHE_DIR=${HOME}/.cache/composer \
    --env COMPOSER_HOME=${HOME}/.config/composer \
    -v "$(pwd)":"$(pwd)":rw -w "$(pwd)" \
    --add-host db:127.0.0.1 \
    --net=host \
    intera/docker-ci-php:${phpVersion}-ubuntu \
    php${phpVersion} ${remainingArguments}

The script can be used like this:

php.sh 7.3 vendor/bin/phpunit

The first argument 7.3 is the PHP version. After that you can provide the arguments to the PHP command. The example above would run phpunit with PHP version 7.3.

You can also omit the PHP version argument and it will use the default PHP version that is defined in the script. The following command executes phpunit with PHP 7.2:

php.sh vendor/bin/phpunit

Argument Handling

The first block of the script handles the PHP version switching and extracting the remaining arguments that should be passed on to the PHP command.

By default PHP 7.2 is used and all arguments are passed on:

phpVersion=7.2
remainingArguments="$@"

If the first argument is a known PHP version it overwrites the default version and is removed from the arguments that are passed on:

if [[ "$1" =~ (5.6|7.0|7.1|7.2|7.3) ]]; then
    phpVersion=$1
    remainingArguments="${@:2}"
fi

The docker command parts

Let’s walk though the different parts of the docker command.

The first parameters will start an interactive terminal. Without them you won’t get nicely colored output:

--interactive --tty

The container is removed after the command is finished:

--rm

We switch the user and group to the currently logged on user to prevent permission problems. We also need to mount /etc/passwd and /etc/group. Otherwise the container would not know about the name of the current user and his groups. These volumes can be read-only (:ro).

--user $(id -u):$(id -g) \
-v /etc/passwd:/etc/passwd:ro \
-v /etc/passwd:/etc/group:ro \

The Composer directories from the user’s home directory are mounted to make sure the Composer cache is persisted and it has access to its config:

-v ${HOME}/.config/composer:${HOME}/.config/composer:rw \
-v ${HOME}/.cache/composer:${HOME}/.cache/composer:rw \
--env COMPOSER_CACHE_DIR=${HOME}/.cache/composer \
--env COMPOSER_HOME=${HOME}/.config/composer \

The current directory is mounted as a volume and the working directory of the Docker command is changed to this directory. Without access to your project files executing PHP would not make much sense 😉

Important! Please be aware that all files required by PHP (or Composer) must be subfolders of the current working directory. Symlinks that point outside that folder will not work.

-v "$(pwd)":"$(pwd)":rw -w "$(pwd)" \

The network part

In some of my (TYPO3) projects a Composer script is executed after install / update that needs access to the database (TYPO3 Console).

The database is running in a docker container and its port is mapped to my localhost. This allows me to use the following configuration:

--net=host \
--add-host db:127.0.0.1 \

The net=host option connects the container with the host network which allows it to access the database.

With add-host you can add additional hostname entries. In my case the Docker container running the database is called db which is also used as database hostname in the application config. With the entry above the db host will be resolved to your localhost.

The SSH part

This part is only required when you need SSH authentication. A common use case is loading private Git repositories via Composer.

The .ssh folder is mounted from the user’s home directory. This gives us access to the SSH config, the key files and the known_hosts file. You might be able to change this to a read-only volume when neither of these two conditions apply:

• not all SSH hosts are present in your known_hosts file and SSH needs to update it
• you are using a persistent SSH connection (ControlMaster, ControlPath, ControlPersist) and its path is located in your ~/.ssh folder

We also forward the socket of your SSH agent to use passwordless authentication:

-v ${HOME}/.ssh:${HOME}/.ssh:rw \
-v ${SSH_AUTH_SOCK}:/ssh-auth.sock \
--env SSH_AUTH_SOCK=/ssh-auth.sock \

The image

The Docker image is custom made and based on Ubuntu and the awesome PPA of Ondřej Surý.

It is publicly available on Docker Hub in PHP version 5.6 to 7.3.

The tag is switched depending on the selected PHP version.

Of course you can use your own image.

intera/docker-ci-php:${phpVersion}-ubuntu \

The PHP command (finally!)

The PHP command is switched based on the selected PHP version.

Finally the arguments passed to the command are forwarded to Composer.

php${phpVersion} ${remainingArguments}

Composer addon

The Docker images described above already contain a Composer executable at /usr/local/bin/composer.phar. This is an example to make use of it:

php.sh /usr/local/bin/composer.phar install

You can make your life even easier when you wrap the command above in another shell script that directly calls Composer:

#!/usr/bin/env bash

THIS_SCRIPT_DIR="$( cd "$( dirname `readlink -f "${BASH_SOURCE[0]}"` )" >/dev/null && pwd )"

phpVersion=7.2
remainingArguments="$@"

if [[ "$1" =~ (5.6|7.0|7.1|7.2|7.3) ]]; then
    phpVersion=$1
    remainingArguments="${@:2}"
fi

${THIS_SCRIPT_DIR}/php.sh ${phpVersion} /usr/local/bin/composer.phar ${remainingArguments}

Now you can just call

composer.sh install

SELinux

There might be issues with Linux distributions using SELinux.

I will publish another article soon that will provide solutions to these problems.