shinsenter/php repository overview

⁠PHP Docker Images

📦 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

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

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

Explore all available tags on our Docker Hub⁠.

⁠Examples

You can easily run a container by copying and pasting one of these docker run 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

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.

⁠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

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

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

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

For example, to run a container 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

Or in a docker-compose.yml:

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

⁠Hooks

Hooks are useful for customizing the behavior of a running container.
These images support the following hooks:

To use hooks, create a hooks folder inside $APP_PATH and add executable files named after the hook, or in subfolders with the same name. Example: to install PHP modules at first-run, add a script hooks/first-run or hooks/first-run/install-modules.

Set DEBUG=1 to see which hooks are executed.

⁠Autorun Scripts

Shell scripts placed in the /startup/ directory will automatically run when the container starts, in alphabetical order by filename. This feature can initialize projects before the main program runs, saving time by executing initialization scripts automatically.

⁠Usage Example

Copy a script called 00-migration into /startup/ via a 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/

⁠Disable Autorun Scripts

To disable autorun scripts, set DISABLE_AUTORUN_SCRIPTS=1 as an environment variable.

For example, with docker run:

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

Or in docker-compose.yml:

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

⁠Using Cron Jobs

To enable cron jobs in containers, you can start the container with ENABLE_CRONTAB=1. This setting activates the Crontab service, which loads settings from the directory specified by $CRONTAB_DIR (default is /etc/crontab.d).

The cron jobs will run as the user defined by $APP_USER:$APP_GROUP, which by default is www-data:www-data, and with the home directory set by $CRONTAB_HOME (default is /var/www/html).

Here is an example Dockerfile to add a crontab:

FROM shinsenter/php:latest

ENV ENABLE_CRONTAB=1

# create crontab entry via RUN instruction
RUN echo '* * * * * 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/

The format of a crontab entry is as follows:

# Job definition:
# .---------------- minute (0 - 59)
# |  .------------- hour (0 - 23)
# |  |  .---------- day of month (1 - 31)
# |  |  |  .------- month (1 - 12) OR jan,feb,mar,apr ...
# |  |  |  |  .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
# |  |  |  |  |
# *  *  *  *  *  command to be executed

You can also easily set up cron jobs through the $CRONTAB_SETTINGS environment variable in the docker-compose.yml file. When the container starts, these settings are loaded into crontab, giving you more flexibility to change them later.

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 information on environment variables for cron jobs, refer to the Other System Settings⁠ section below.

⁠Customize Supervisor Command

We can set a $SUPERVISOR_PHP_COMMAND environment variable to the service definition in your application's docker-compose.yml file. This environment variable will contain the command that the container will use to serve your application using another process instead of the default process.

⁠Command Line

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

⁠With docker-compose.yml

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

⁠Sending Emails

In these Docker images, sendmail has been replaced by msmtp for sending emails. You can send emails using common PHP libraries like PHPMailer⁠.

If you prefer to use PHP's mail() function, you'll need to configure SMTP using the following environment variables in your container:

⁠Debug Mode

Enable "debug mode" for more verbose logging by setting DEBUG=1 as an environment variable. This can be used both with docker run and in docker-compose.yml.

⁠Command Line

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

⁠With docker-compose.yml

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

⁠Other System Settings

These Docker images include additional environment variables for fine-tuning container behavior:

⁠Supported Platforms

Check our Docker Hub⁠ for all available platforms. The Docker images are available for both Debian and Alpine versions.

⁠Stable Image Tags

For stable versions (with date tagged) you can depend on in production, we also apply version tags on another repository.

⁠Contributing

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

Your support helps maintain and improve these images for the community.

⁠License

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

Please respect the intellectual efforts involved in creating these images. If you intend to copy or use ideas from this project, proper credit is appreciated.

From Vietnam 🇻🇳 with love.