shinsenter/php repository overview

⁠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 official PHP Docker images⁠ 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 Apache2⁠, Nginx⁠, RoadRunner⁠, and FrankenPHP⁠. This helps you start projects faster without extra installs.

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

See all tags on our Docker Hub⁠.

⁠Examples

Run a container using one of these commands:

⁠CLI

# 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

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

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

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

⁠Examples

⁠Command Line

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

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

⁠Pre-installed PHP Extensions

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

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

⁠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:

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/

⁠Application Directory

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

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:

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

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:

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:

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/

⁠Disable Autorun Scripts

To disable autorun scripts, set DISABLE_AUTORUN_SCRIPTS=1:

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

Or in docker-compose:

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, consider 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:

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:

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:

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

docker-compose example:

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 PHPMailer⁠.

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

⁠Debug Mode

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

Command line:

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

docker-compose:

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 Docker Hub⁠ 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.

⁠Contributing

If you find these images useful, consider donating via PayPal⁠ or open an issue on GitHub⁠.

Your support helps maintain and improve these images for everyone.

⁠License

This project is licensed under the GNU General Public License v3.0⁠.

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

From Vietnam 🇻🇳 with love.