shinsenter/php Docker Image

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 the latest Composer and common web servers - [] [] RoadRunner, and https://frankenphp.dev - so you don't need to install them separately.

🪶 Note: We slim these images down with the https://code.shin.company/docker-squash project, so pulls are faster and they use less disk and memory than the official images they're based on.

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).

This convention lets you map any environment variable straight back to its ini/fpm 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 and configure extensions in one step - no need for docker-php-ext-install or manual php.ini edits.

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; build a custom image for advanced cron features.

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, so libraries like https://github.com/PHPMailer/PHPMailer work out of the box.

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 these images are useful to you, donate via *** or open an issue on https://code.shin.company/php/issues/new.

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.