PHP Docker Images

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

Docker Hub: https://hub.docker.com/r/shinsenter/php

Introduction

Our PHP Docker images are built on top of the official PHP Docker images. These images allow easy tweaking of PHP and PHP-FPM settings through environment variables, eliminating the need to rebuild images when changing settings.

These images also include the latest version of Composer, along with well-known web servers like Apache2, Nginx, Nginx Unit, or FrankenPHP, enabling projects to get started faster without additional installation.

🪶 Note: Although built on top of the official PHP images and including more useful extensions, we have drastically reduced the image sizes compared to the base images while maintaining compatibility. This optimization improves download times and resource usage without sacrificing functionality, thanks to the docker-squash project.

Image Variants

The image tags cover PHP versions from 7.1 to 8.3, available in cli, fpm, fpm-nginx, fpm-apache, frankenphp⁽¹⁾, and unit-php⁽²⁾ variants.

For example:

• shinsenter/php:7.3-cli
• shinsenter/php:7.4-fpm
• shinsenter/php:8.0-fpm-apache
• shinsenter/php:8.1-fpm-nginx
• shinsenter/php:8.2-frankenphp ⁽¹⁾
• shinsenter/php:8.3-unit-php ⁽²⁾

Check our Docker Hub for all available tags.

For stable versions you can depend on in production, we also apply version tags on another repository.

💡 Hint: Docker image tags ending in -alpine or -tidy indicate Docker images built on the Alpine Linux base operating system. These Docker images are lightweight, helping to speed up builds and save bandwidth for your CI/CD pipelines.

⁽¹⁾: FrankenPHP is still in BETA. The frankenphp variant supports PHP >= 8.2.
⁽²⁾: PHP with Nginx Unit. The unit-php variant supports PHP >= 7.4.

Examples

You can simply copy and paste one of these docker run commands to run a container:

CLI

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

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

PHP-FPM

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

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

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

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

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

# with Nginx Unit
docker run --rm -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.3-unit-php

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.

💡 Hint: Run env-default or env | sort | grep PHP_ in the container to get a full list of default environment values.

Examples

Command Line

docker run --rm \
    -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.3 php -i

docker-compose.yml

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

Explanation

💡 Hint: Run env-default or env | sort | grep PHP_ in the container to get a full list of default environment values.

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
redis
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.3-cli php -m in the container to get a list of extensions (you can replace 8.3 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.3-fpm-nginx

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

👉🏻 Info: The phpaddmod command is a wrapper around the install-php-extensions 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 the install-php-extensions project.

Application Directory

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

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

This would change the web application directory to /app.

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

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

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

Customize Container User and Group in Docker

The Docker image likely has a default user and group set, such as www-data for a web server image. However, you can override these defaults by setting environment variables when running the container.

The available variables are:

For example, to run a container as the user myapp with uid 5000, you could do:

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

Or in a docker-compose.yml:

services:
  web:
    image: shinsenter/php:8.3-fpm-nginx
    environment:
      - APP_USER=myapp
      - APP_UID=5000

Autorun Scripts

Shell scripts copied into the /startup/ directory of the container will automatically run when the container starts, in alphabetical order by filename.

This mechanism can be used to initialize projects before the main program on the container runs. The autorun feature saves time by executing initialization scripts without manual intervention.

Usage

For example, a script called 00-copy-config could be copied into /startup/ via a Dockerfile.

Note: The script file must have executable permissions to run.

FROM shinsenter/php:8.3-cli

ADD ./application /var/www/html
ADD ./autorun/00-copy-config /startup/00-copy-config
RUN chmod +x /startup/00-copy-config

👉🏻 Info: The startup directory already includes a script called 99-greeting that prints a welcome message when the container starts:

     _     _                      _              __    _
    | |   (_)                    | |            / /   | |
 ___| |__  _ _ __  ___  ___ _ __ | |_ ___ _ __ / / __ | |__  _ __
/ __| '_ \| | '_ \/ __|/ _ \ '_ \| __/ _ \ '__/ / '_ \| '_ \| '_ \
\__ \ | | | | | | \__ \  __/ | | | ||  __/ | / /| |_) | | | | |_) |
|___/_| |_|_|_| |_|___/\___|_| |_|\__\___|_|/_/ | .__/|_| |_| .__/
                                                | |         | |
                                                |_|         |_|
Github:    https://code.shin.company/php
DockerHub: https://docker.shin.company/php

(To edit this welcome message, add your text to /etc/welcome.txt)

----------------------------------------
Container      : shinsenter/php
Distro         : Alpine Linux v3.19
Timezone       : UTC (GMT+0000)
UID / GID      : www-data:www-data (82:82)
App Root       : /var/www/html
Document Root  : /var/www/html/public
----------------------------------------

PHP Docker Images (https://hub.docker.com/r/shinsenter/php)
Copyright (C) 2024  SHIN (@shinsenter)

This is free software under the GNU GPL.
You can redistribute and/or modify it under the terms of the GNU GPL.
This program is distributed in the hope it will be useful,
but WITHOUT ANY WARRANTY. See the GNU GPL for more details.

To get support, please contact: SHIN (@shinsenter)

PHP 8.3.3 (fpm-fcgi) (built: Feb 16 2024 23:20:45)
Copyright (c) The PHP Group
Zend Engine v4.3.3, Copyright (c) Zend Technologies
    with Zend OPcache v8.3.3, Copyright (c), by Zend Technologies
Composer version 2.7.1 2024-02-09 15:26:28

Disable autorun scripts

To disable autorunning scripts, set the DISABLE_AUTORUN_SCRIPTS environment variable to 1.

For example, you can do this with docker run:

docker run --rm -e DISABLE_AUTORUN_SCRIPTS=1 shinsenter/php:8.3-fpm-nginx

Or in a docker-compose.yml:

services:
  web:
    image: shinsenter/php:8.3-fpm-nginx
    environment:
      - DISABLE_AUTORUN_SCRIPTS=1

Debug mode

Sometimes you may need a "debug mode" for more verbose logging.

You can pass DEBUG=1 as an environment variable to the container for more verbose logging. The application can check for this and enable debug mode, outputting more logs.

This works both with docker run and in docker-compose.yml.

Command Line

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

docker-compose.yml

services:
  web:
    image: shinsenter/php:8.3-fpm-nginx
    environment:
      - DEBUG=1

Other System Settings

These Docker images also include other environment variables for fine-tuning the behavior of the container.

Supported Platforms

Check our Docker Hub for all available platforms.

💡 Hint: Docker image tags ending in -alpine or -tidy indicate Docker images built on the Alpine Linux base operating system. These Docker images are lightweight, helping to speed up builds and save bandwidth for your CI/CD pipelines.

Stable Image Tags

We build new Docker images daily to ensure they stay up-to-date with the latest upstream updates for PHP, base OS, Composer, etc. The images in this repo are regularly updated under the same tag names.

For stable versions you can depend on in production, we also apply version tags on another repository.

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

This way, you get frequently updated images under static tags, providing both the latest code and production stability.

Contributing

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

Your support helps keep these images maintained and improved for the community.

License

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

I appreciate you respecting my intellectual efforts in creating them. If you intend to copy or use ideas from this project, please credit properly.

From Vietnam 🇻🇳 with love.