shinsenter/php

PHP Docker Images

📦 Lightweight PHP Docker images designed for easy customization and simple extension management.

Our images support PHP versions from 5.6 up to 8.6 (RC), with variants for CLI, ZTS, FPM, FPM/Apache, FPM/Nginx, RoadRunner, and FrankenPHP. Images are available for both Debian and Alpine.

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

Table of Contents

• 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

These images are based on the https://hub.docker.com/_/php and make it easy to change PHP and PHP-FPM settings using environment variables. No image rebuild required.

They include Composer (the latest version) and common web servers such as [] [] RoadRunner, and [***] This helps you start projects faster without extra installs.

🪶 Note: While based on the official images and including useful extensions, we have significantly reduced the image sizes to improve download times and resource usage, using the https://code.shin.company/docker-squash project.

Docker Image Variants

Tags cover PHP versions from 5.6 to 8.6-rc and come in cli, zts, fpm, fpm-nginx, fpm-apache, roadrunner⁽¹⁾, and frankenphp⁽²⁾ variants. Both Debian and Alpine builds are available.

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 ⁽²⁾

⁽¹⁾ RoadRunner variant — requires PHP >= 8.0.
⁽²⁾ FrankenPHP variant is BETA — requires PHP >= 8.2.

See all tags on our https://hub.docker.com/r/shinsenter/php/tags.

Examples

Run a container using one of these commands:

CLI

shell
# 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

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

PHP-FPM + Nginx (or Apache, RoadRunner, FrankenPHP)

shell
# 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

You can configure PHP and PHP-FPM using environment variables instead of rebuilding images.

Naming rules:

• Variables start with PHP_ to avoid conflicts.
• The remainder matches the php.ini or php-fpm.conf directive name.
  • 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 replacing dots or dashes).

By following this convention you can quickly identify the environment variable that maps to each configuration directive.

👉🏻 Note: By default, $PHP_* variables are applied only if set before the container starts. To allow changing PHP settings from an interactive shell inside a running container, start the container with ALLOW_RUNTIME_PHP_ENVVARS=1.

💡 Tip: Run php-envvars inside the container to list the default $PHP_* variables.

Examples

Command Line

shell
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

yaml
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

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

Pre-installed PHP Extensions

Common PHP extensions are pre-installed so projects can start quickly.

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

👉🏻 Note: Extensions that are already included in the official PHP images are not listed here.

💡 Tip: Run docker run --rm shinsenter/php:8.5-cli php -m (replace 8.5 as needed) to see installed extensions.

Adding PHP Extensions

Use the phpaddmod helper to install extensions easily.

You do not need to use docker-php-ext-install or manually edit php.ini — phpaddmod installs and configures extensions for you.

Example Dockerfile:

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/

👉🏻 Note: phpaddmod is a wrapper around the https://github.com/mlocati/docker-php-extension-installer, which handles compiling and enabling extensions.

💡 Tip: See the supported extensions in their documentation: https://github.com/mlocati/docker-php-extension-installer/blob/master/README.md#supported-php-extensions

Application Directory

Default application directory: /var/www/html. Change it with $APP_PATH:

shell
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

To change the document root (a path inside $APP_PATH that contains index.php), set $DOCUMENT_ROOT:

shell
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 example sets the document root to /app/public.

Customizing Container User and Group in Docker

Override the default user and group with environment variables:

Example (run as user myapp with UID 5000):

shell
docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -e APP_USER=myapp \
    -e APP_UID=5000 \
    shinsenter/php:8.5-fpm-nginx

docker-compose example:

yaml
services:
  web:
    image: shinsenter/php:8.5-fpm-nginx
    environment:
      APP_USER: "myapp"
      APP_UID: "5000"

Hooks

Hooks let you customize runtime behavior. Create a hooks folder inside $APP_PATH and place executable files named after each hook (or use subfolders).

Supported hooks:

Example: To install PHP modules on first run, add hooks/first-run or hooks/first-run/install-modules.

Enable DEBUG=1 to see which hooks run.

Autorun Scripts

Place shell scripts in /startup/ to run automatically when the container starts. Scripts run in alphabetical order by filename.

Example Dockerfile to add an autorun script:

Ensure the script is executable.

Dockerfile
FROM shinsenter/php:8.5-cli

ADD ./autorun/00-migration /startup/00-migration
RUN chmod +x /startup/00-migration

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

👉🏻 Note: The startup directory includes 99-greeting, which prints a welcome message at startup.

Disable Autorun Scripts

To disable autorun scripts, set DISABLE_AUTORUN_SCRIPTS=1:

shell
docker run -e DISABLE_AUTORUN_SCRIPTS=1 shinsenter/ubuntu-s6:latest bash

Or in docker-compose:

yaml
services:
  web:
    image: shinsenter/ubuntu-s6:latest
    environment:
      DISABLE_AUTORUN_SCRIPTS: "1"

Using Cron Jobs

This project supports simple cron jobs. For advanced cron features, *** building a custom image.

Enable cron with ENABLE_CRONTAB=1. The service loads jobs from $CRONTAB_DIR (default: /etc/crontab.d) and runs them as $APP_USER:$APP_GROUP (default www-data:www-data), with $CRONTAB_HOME (default: /var/www/html) as the home directory.

Example Dockerfile to add a crontab:

Dockerfile
FROM shinsenter/php:latest

ENV ENABLE_CRONTAB=1

# create crontab entry via RUN instruction
RUN echo '* * * * * echo "This line will run every minute!" | tee /tmp/cron-every-minute.txt' >> /etc/crontab.d/sample1;

# or copy crontab entries via ADD instruction
ADD ./sample2 /etc/crontab.d/

Crontab entry format:

# .---------------- minute (0 - 59)
# |  .------------- hour (0 - 23)
# |  |  .---------- day of month (1 - 31)
# |  |  |  .------- month (1 - 12) OR jan,feb,...
# |  |  |  |  .---- day of week (0 - 6) OR sun,mon,...
# |  |  |  |  |
# *  *  *  *  *  command to be executed

You can set cron jobs directly via the CRONTAB_SETTINGS environment variable in docker-compose:

yml
services:
  web:
    image: shinsenter/php:8.5-fpm-nginx
    environment:
      ENABLE_CRONTAB: "1"
      CRONTAB_SETTINGS: "* * * * * echo 'This line will run every minute!' | tee /tmp/cron-every-minute.txt"

For more cron-related environment variables, see Other System Settings.

Customize Supervisor Command

Set SUPERVISOR_PHP_COMMAND to override the default command used by the supervisor process. This lets you run a different command to serve your app.

Command line example:

shell
docker run \
    -e SUPERVISOR_PHP_COMMAND='php -S localhost:80 index.php' \
    shinsenter/php:8.5

docker-compose example:

yml
services:
  web:
    image: shinsenter/php:8.5
    environment:
      SUPERVISOR_PHP_COMMAND: "php -S localhost:80 index.php"

Sending Emails

We use msmtp as a lightweight sendmail replacement. You can send mail with libraries like https://github.com/PHPMailer/PHPMailer.

To use PHP's mail() function, configure SMTP via these environment variables:

💡 Tip: If you don't have an SMTP server, try using a local SMTP container like https://hub.docker.com/r/axllent/mailpit. With Mailpit, set SMTP_HOST=mailpit and SMTP_PORT=1025 in your container.

Debug Mode

Enable verbose logging by setting DEBUG=1 when starting the container.

Command line:

shell
docker run -e DEBUG=1 shinsenter/php:8.5-fpm-nginx

docker-compose:

yml
services:
  web:
    image: shinsenter/php:8.5-fpm-nginx
    environment:
      DEBUG: "1"

Other System Settings

Additional environment variables for fine-tuning container behavior:

Supported Platforms

See our https://hub.docker.com/r/shinsenter/php/tags for available platforms. Images are built for both Debian and Alpine variants.

Stable Image Tags

For stable, production-ready images we maintain dated tags in a separate repository.

👉🏻 View Stable Tags: https://hub.docker.com/r/shinsenter/php-archives/tags

Contributing

If you find these images useful, *** donating via *** or open an issue on https://code.shin.company/php/issues/new.

Your support helps maintain and improve these images for everyone.

License

This project is licensed under the https://code.shin.company/php/blob/main/LICENSE.

Please respect the work that went into these images. If you reuse ideas from this project, credit is appreciated.

---

From Vietnam 🇻🇳 with love.