PHP Docker images for development

PHP/PHP-FPM/Jenkins Docker images for development/CI, based on Alpine Linux for minimal size

Bundled with:

• UTC timezone
• Latest Xdebug (3.x) configured and enabled for development and debugging
• Latest Composer (2.x) installed globally
• Installed PHP extensions: Multibyte String, cURL, Intl, OpenSSL, Zlib, BCMath, GD, OPcache
• Installed PECL extensions: APCu
• Includes make utility
• Automatic Healthcheck on PHP-FPM images

Available tags

CLI

latest	PHP 8.3	Dockerfile
cli-latest	PHP 8.3	Dockerfile
cli	PHP 8.3	Dockerfile
8	PHP 8.3	Dockerfile
8.3	PHP 8.3	Dockerfile
8.2	PHP 8.2	Dockerfile
8.1	PHP 8.1	Dockerfile
8.0	PHP 8.0	Dockerfile
7	PHP 7.4	Dockerfile
7.4	PHP 7.4	Dockerfile

FPM

fpm-latest	PHP 8.3	Dockerfile
fpm	PHP 8.3	Dockerfile
8-fpm	PHP 8.3	Dockerfile
8.3-fpm	PHP 8.2	Dockerfile
8.2-fpm	PHP 8.2	Dockerfile
8.1-fpm	PHP 8.1	Dockerfile
8.0-fpm	PHP 8.0	Dockerfile
7-fpm	PHP 7.4	Dockerfile
7.4-fpm	PHP 7.4	Dockerfile

Jenkins

jenkins-latest	PHP 8.3	Dockerfile
jenkins	PHP 8.3	Dockerfile
8-jenkins	PHP 8.3	Dockerfile
8.3-jenkins	PHP 8.3	Dockerfile
8.2-jenkins	PHP 8.2	Dockerfile
8.1-jenkins	PHP 8.1	Dockerfile
8.0-jenkins	PHP 8.0	Dockerfile
7-jenkins	PHP 7.4	Dockerfile
7.4-jenkins	PHP 7.4	Dockerfile

Jenkins' images are specially designed to be run as a Jenkins slave on a CI pipeline

Environment variables

General

STDOUT_LOG

• Type: int
• Default: 0

Output logs to stdout by setting a non zero value. By default PHP errors are sent to /var/log/php/php.log

This setting does not affect Xdebug session logs which will still be sent to /var/log/php/debug.log

Xdebug

XDEBUG_DISABLE

• Type: int
• Default: 0
• Not recommended, use XDEBUG_MODE=off instead

Disable Xdebug by setting a non zero value

XDEBUG_MODE

• Type: string
• Default: develop,coverage,debug
• To disable Xdebug set to off

Running Xdebug mode. Review xdebug.mode documentation

XDEBUG_CLIENT_HOST

• Type: string
• Default: auto-discovered host

The remote server host to connect to

Auto discovery tries to use host.docker.internal host if defined or automatically detects remote host IP

XDEBUG_CLIENT_PORT

• Type: integer
• Default: 9003

The remote server port to connect to

XDEBUG_FILE_LINK_FORMAT

• Type: string
• Default: not set

Protocol format to integrate IDEs with stack trace file links. You can provide your custom format or use one of the following: phpstorm, idea, vscode, sublime, netbeans, atom, vim, emacs, gvim, textmate or macvim.

If you use your custom format remember to escape the string for use in "sed". Review xdebug.file_link_format documentation

Environment update guide

Due to the upgrade to Xdebug 3 some environment variables have been changed or removed from previous versions

• XDEBUG_REMOTE_HOST and XDEBUG_REMOTE_PORT have been renamed to XDEBUG_CLIENT_HOST and XDEBUG_CLIENT_PORT
• Default remote port for debug session has changed to 9003
• XDEBUG_REMOTE_AUTOSTART has been removed, see Starting a Xdebug debug session
• XDEBUG_IDE_KEY has been removed, if needed, extend the image to include it as a Xdebug config
• XDEBUG_PROFILER_ENABLE and XDEBUG_AUTO_TRACE have been removed, their functionality is now controlled by XDEBUG_MODE

OPcache

OPCACHE_VALIDATE_TIMESTAMP

• Type: int
• Default: 1

Disable file timestamp validation by setting to 0

OPCACHE_MEMORY_CONSUMPTION

• Type: int
• Default: 128

Memory consumption limit in megabytes

OPCACHE_MAX_ACCELERATED_FILES

• Type: int
• Default: 1000

Max number of in-memory cached files

Volumes

/app

The default working directory. You should mount your project root path in this volume

/var/log/php

Logging volume for PHP logs, PHP-FPM logs and Xdebug files

Usage

Getting the image

docker pull juliangut/phpdev:latest

docker pull juliangut/phpdev:fpm-latest

docker pull juliangut/phpdev:jenkins-latest

Running a container

docker run --rm -it -v `pwd`:/app juliangut/phpdev:latest

docker run -d -v `pwd`:/app juliangut/phpdev:fpm-latest

Running built-in server

docker run -d -p 8080:8080 -v `pwd`:/app juliangut/phpdev:latest php -S 0.0.0.0:8080 -t /app/public

With Docker Compose

version: "3"

services:
  app:
    image: juliangut/phpdev:latest
    ports:
      - 8080:8080
    volumes:
      - .:/app
    command: "php -S 0.0.0.0:8080 -t /app/public"

Access running server on "http://localhost:8080"

Running a composer command

docker run --rm -v `pwd`:/app juliangut/phpdev:latest composer [command]

docker run --rm -v `pwd`:/app juliangut/phpdev:fpm-latest composer [command]

Composer authentication

If you work with privately hosted packages and repositories and your local composer is already configured you can share that configuration with your containers

docker run --rm -v `pwd`:/app -v ~/.composer/auth.json:/home/docker/.composer/auth.json juliangut/phpdev:latest composer [command]

Accessing a running container

docker exec -it [container_id] /bin/bash

Starting a Xdebug debug session

The way of starting a debug session is by dynamically setting a session identifier by one of the following means

CLI

This will enable XDebug for each and every request

• Setting "XDEBUG_SESSION" environment variable on container start

Browser

This allows to specify which requests will have XDebug enabled

• Setting "XDEBUG_SESSION" cookie with the session identifier as its value. eg: curl -b "XDEBUG_SESSION=PHPSTORM" http://localhost:8080/
• On HTTP request by adding "XDEBUG_SESSION_START" query parameter to the URI. eg: curl http://localhost:8080?XDEBUG_SESSION_START=PHPSTORM
• On POST requests by adding a "XDEBUG_SESSION_START" parameter. eg: curl -X POST -F "XDEBUG_SESSION_START=PHPSTORM" http://localhost:8080

Browser support

There are browser plugins/extensions available to very easily toggle the required cookies

Debugging with PHPStorm

Review Xdebug configuration

• Debug port must be the same previously defined in XDEBUG_CLIENT_PORT environment variable (9003 by default)

Create a server

• Server name will be used later so make it relevant
• Set 0.0.0.0 as Host to allow any
• Map your project root to /app

Start debugging

Start listening for incoming connections by toggling Run > Start Listening for PHP Debug Connections, or by clicking the phone icon

Start the container

Setting PHP_IDE_CONFIG environment variable to the server name you defined earlier, this will instruct PHPStorm which mapping to use

docker run -d -p 8080:8080 -e XDEBUG_SESSION="PHPSTORM" -e PHP_IDE_CONFIG="serverName=Testing" -v `pwd`:/app --add-host host.docker.internal:host-gateway juliangut/phpdev:latest php -S 0.0.0.0:8080 -t /app/public

Using Docker Compose

version: "3"

services:
  app:
    image: juliangut/phpdev:latest
    ports:
      - 8080:8080
    environment:
      XDEBUG_SESSION: PHPSTORM
      PHP_IDE_CONFIG: serverName=Testing
    volumes:
      - .:/app
    extra_hosts:
      - host.docker.internal:host-gateway
    command: "php -S 0.0.0.0:8080 -t /app/public"

Firewalld & NetworkManager notice

By default, firewalld blocks all outgoing connections from docker containers, such as Xdebug connection to port 9003 on the host. In order to allow docker containers to connect with Xdebug server you need to include docker0 interface into a "trusted" zone both on NetworkManager and firewalld:

Assign docker0 interface to "trusted" zone and stop NetworkManager service

nmcli connection modify docker0 connection.zone trusted
systemctl stop NetworkManager.service

Assign "trusted" zone for docker0 interface on firewalld. Additionally, 172.0.0.0/8 source is added to cover any created docker network

firewall-cmd --permanent --zone=trusted --change-interface=docker0
firewall-cmd --permanent --zone=trusted --add-source=172.0.0.0/8
firewall-cmd --reload

Restart NetworkManager and reassign docker0 interface, just in case

systemctl start NetworkManager.service
nmcli connection modify docker0 connection.zone trusted

Restart docker service, so it recreates its iptables

systemctl restart docker.service

Extending the image

The image comes with just the bare minimum PHP extensions, you will most probably need more

This is an example on extending the image adding extra extensions and composer dependencies

FROM juliangut/phpdev:latest

# Add PHP extensions
RUN set -xe \
  && apk add --no-cache --virtual .build-deps \
    $PHPIZE_DEPS \
  \
  && docker-php-ext-configure \
    pdo_mysql \
      --with-pdo-mysql=mysqlnd \
  && docker-php-ext-install \
    pdo_mysql \
  \
  && pecl install \
    apcu \
    redis \
  && docker-php-ext-enable \
    apcu \
    redis \
  \
  && apk del .build-deps \
  && rm -rf /tmp/* /var/cache/apk/*

# Add global composer dependencies as 'docker' user
USER docker
RUN composer global require phpunit/phpunit

# Remember to always return to user 'root'
USER root

Requiring Composer V1

If for whatever reason you need Composer downgraded to version 1

FROM juliangut/phpdev:latest

RUN composer self-update --1

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before

License

See file LICENSE included with the source code for a copy of the license terms