PHP Docker Images <!-- omit from toc -->

📦 Simplified PHP Docker images for effortless customization and extension setup.

Our Docker images cover PHP versions from 5.6 to 8.5 (beta), available in CLI, ZTS, FPM, FPM/Apache2, FPM/Nginx, RoadRunner and FrankenPHP variants. The Docker images are available for both Debian and Alpine versions.

• Docker Hub: https://hub.docker.com/r/shinsenter/php
• GitHub Packages: https://code.shin.company/php/pkgs/container/php
• You can also find and use other pre-built Docker images for some popular PHP applications and frameworks here.

Table of Contents <!-- omit from toc -->

• Introduction
• Docker Image Variants
• Customizing Settings via Environment Variables
• Pre-installed PHP Extensions
• Adding PHP Extensions
• Application Directory
• Customizing Container User and Group in Docker
• Hooks
• Autorun Scripts
• Using Cron Jobs
• Customize Supervisor Command
• Sending Emails
• Debug Mode
• Other System Settings
• Supported Platforms
• Stable Image Tags
• Contributing
• License

Introduction

Our PHP Docker images are based on the official PHP Docker images. These images facilitate the easy adjustment of PHP and PHP-FPM settings using environment variables, eliminating the need to rebuild images when making configuration changes.

These images also come with the latest version of Composer and popular web servers like Apache2, Nginx, RoadRunner or FrankenPHP. This setup allows for faster project initiation without additional installations.

🪶 Info: While built on the official PHP images and including more useful extensions, we have significantly reduced the image sizes compared to the base images. This optimization improves download times and resource usage without sacrificing functionality, thanks to the docker-squash project.

Docker Image Variants

Our image tags cover PHP versions from 5.6 to 8.5, available in cli, zts, fpm, fpm-nginx, fpm-apache, roadrunner⁽¹⁾, and frankenphp⁽²⁾ variants. The Docker images are available for both Debian and Alpine versions.

Examples:

• shinsenter/php:8.3-cli
• shinsenter/php:8.4-zts
• shinsenter/php:8.5-fpm
• shinsenter/php:8.1-fpm-apache
• shinsenter/php:8.2-fpm-nginx
• shinsenter/php:8.3-roadrunner ⁽¹⁾
• shinsenter/php:8.4-frankenphp ⁽²⁾

⁽¹⁾: PHP with RoadRunner server. The roadrunner variant supports PHP >= 8.0.<br> ⁽²⁾: FrankenPHP is still in BETA. The frankenphp variant supports PHP >= 8.2.<br>

Explore all available tags on our Docker Hub.

Examples <!-- omit from toc -->

You can easily run a container by copying and pasting one of these docker run commands:

CLI <!-- omit from toc -->

# non-interactive
docker run --rm shinsenter/php:8.5-cli php -m

# interactive
docker run -it -v ./myproject:/var/www/html shinsenter/php:8.5-cli

PHP-FPM <!-- omit from toc -->

docker run -v ./myproject:/var/www/html -p 9000:9000 shinsenter/php:8.5-fpm

PHP-FPM + Nginx (or Apache, RoadRunner, FrankenPHP) <!-- omit from toc -->

# with Nginx
docker run -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.5-fpm-nginx

# with Apache
docker run -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.5-fpm-apache

# with RoadRunner
docker run -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.4-roadrunner

# with FrankenPHP
docker run -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.4-frankenphp

Customizing Settings via Environment Variables

These images allow customizing PHP and PHP-FPM settings through environment variables instead of rebuilding images.

The environment variable names follow these conventions:

• Variables are prefixed with PHP_ to avoid conflicts with other application variables.
• The rest of the variable name matches the configuration directive name from php.ini or php-fpm.conf:
  • PHP ini directives: https://www.php.net/manual/en/ini.list.php
  • PHP-FPM directives: https://www.php.net/manual/en/install.fpm.configuration.php
• Directive names are converted to CONSTANT_CASE - uppercase with underscores instead of dots or dashes.

This naming convention helps you easily identify which environment variable applies to which PHP/PHP-FPM configuration directive.

👉🏻 Info: By default, the $PHP_* environment variables only take effect when set before starting the container. To dynamically change PHP configurations using $PHP_* environment variables while running commands within the container, you need to start your container with the ALLOW_RUNTIME_PHP_ENVVARS=1 environment variable.

💡 Hint: Run php-envvars in the container to get a full list of default $PHP_* environment variables.

Examples <!-- omit from toc -->

Command Line <!-- omit from toc -->

docker run \
    -v ./myproject:/var/www/html \
    -e PHP_DISPLAY_ERRORS='1' \
    -e PHP_POST_MAX_SIZE='100M' \
    -e PHP_UPLOAD_MAX_FILESIZE='100M' \
    -e PHP_SESSION_COOKIE_HTTPONLY='1' \
    shinsenter/php:8.5 php -i

With docker-compose.yml <!-- omit from toc -->

services:
  web:
    image: shinsenter/php:8.5-fpm-nginx
    environment:
      PHP_DISPLAY_ERRORS: "1"
      PHP_POST_MAX_SIZE: "100M"
      PHP_UPLOAD_MAX_FILESIZE: "100M"
      PHP_SESSION_COOKIE_HTTPONLY: "1"

Explanation <!-- omit from toc -->

| Environment Variable | Explanation | Equivalent Configuration | |-------------------------------|----------------------------------------------------|-----------------------------| | PHP_DISPLAY_ERRORS=1 | Enables displaying errors during development. | display_errors 1 | | PHP_POST_MAX_SIZE=100M | Increases the maximum post size from the default 8MB. | post_max_size 100M | | PHP_UPLOAD_MAX_FILESIZE=100M | Increases the maximum upload file size from the default 2MB. | upload_max_filesize 100M | | PHP_SESSION_COOKIE_HTTPONLY=1 | Enables the HttpOnly flag for session cookie security. | session.cookie_httponly 1 |

💡 Hint: Run php-envvars in the container to get a full list of default $PHP_* environment variables.

Pre-installed PHP Extensions

Popular PHP extensions are pre-installed by default, allowing projects to get started faster without additional installation.

apcu
bcmath
calendar
exif
gd
gettext
igbinary
intl
msgpack
mysqli
opcache
pcntl
pdo_mysql
pdo_pgsql
pgsql
redis
sodium
tidy
uuid
yaml
zip

👉🏻 Info: The pre-installed PHP extensions from the official Docker images are excluded from this list.

💡 Hint: Run docker run --rm shinsenter/php:8.5-cli php -m in the container to get a list of extensions (you can replace 8.5 with a specific PHP version).

Adding PHP Extensions

These images use a simple command called phpaddmod to install PHP extensions.

You don't need to run the more complex docker-php-ext-install command or manually edit the php.ini file; phpaddmod handles the installation and configuration for you.

For example, in your Dockerfile:

FROM shinsenter/php:8.5-fpm-nginx

# Install imagick, swoole and xdebug
RUN phpaddmod imagick swoole xdebug

# Add your instructions here
# For example:
# ADD --chown=$APP_USER:$APP_GROUP ./myproject/ /var/www/html/

👉🏻 Info: The phpaddmod command is a wrapper around the mlocati/docker-php-extension-installer utility, which takes care of all required steps to compile and activate the extensions.

💡 Hint: If you're having trouble figuring out which extensions can be installed, have a look at their documentation.

Application Directory

The default application directory is /var/www/html and can be customized via the $APP_PATH environment variable:

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v "$PWD":/app \
    -e APP_PATH=/app \
    shinsenter/php:8.5-fpm-nginx

This changes the web application directory to /app.

Moreover, the default document root (a relative path inside the $APP_PATH (application directory) that contains your index.php file) can be customized by setting the $DOCUMENT_ROOT environment variable:

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v "$PWD":/app \
    -e APP_PATH=/app \
    -e DOCUMENT_ROOT=public \
    shinsenter/php:8.5-fpm-nginx

This would change the document root path to /app/public.

Customizing Container User and Group in Docker

Override the default user and group settings by setting environment variables when running the container.

Available variables:

| Environment Variable | Description | D