PHP Docker Images

Multi-architecture PHP Docker images with extensive extensions for modern web development.

⚠️ Deprecation Notice: PHP 7.x, 8.0 and 8.1 builds are no longer published. Existing images remain available in registries for backwards compatibility. See Deprecated Versions below.

🎯 Which Image Should I Use?

New projects or need process supervision? → Use v2 images (e.g., 8.3-fpm-alpine-v2)
Existing deployments or maximum compatibility? → Use v1 images (e.g., 8.3-fpm-alpine)

See v1 vs v2 comparison below for details.

Features

Multi-Architecture Support: Works on amd64, arm64/aarch64 and arm32v7/armhf platforms
Multiple PHP Versions: PHP 8.2, 8.3, and 8.4 (actively built); PHP 7.x, 8.0, and 8.1 deprecated
Multiple Server Types: CLI, FPM, and Apache
Base OS Options: Alpine (lightweight) and Debian (v1: Bookworm, v2: Trixie with Bookworm-compatible tags)
Extensive Extensions: 30+ PHP extensions pre-installed
Latest Composer: Always ships with the latest Composer version
Image Processing Tools: Includes ImageMagick, GD, and various image optimization utilities
Apache Mods: Includes Apache rewrite module (for Apache variants)
v2: s6-overlay init: Proper PID 1 and service supervision for reliable multi-process containers

ℹ️ Base OS Update (v2 only): v2 Debian images now use Debian Trixie as the base OS (following upstream PHP official images). For backward compatibility, :bookworm tags continue to work and point to the same Trixie-built images. v1 images remain on Bookworm. See migration notes for details.

Environment Variables (v2 only)

The following environment variables are applied at container startup by the s6-overlay init script in v2 images only. v1 images do not process these variables.

Memory Settings

Variable	Default	Description
`PHP_MEMORY_LIMIT`	`256M`	Maximum memory a script can consume
`PHP_OPCACHE_MEMORY_CONSUMPTION`	`128`	OPCache memory consumption limit
`PHP_OPCACHE_INTERNED_STRINGS_BUFFER`	`16`	OPCache interned strings buffer

Upload Settings

Variable	Default	Description
`PHP_UPLOAD_MAX_FILESIZE`	`64M`	Maximum allowed size for uploaded files
`PHP_POST_MAX_SIZE`	`64M`	Maximum size of POST data allowed
`PHP_MAX_FILE_UPLOADS`	`20`	Maximum number of files allowed for upload

Execution Settings

Variable	Default	Description
`PHP_MAX_EXECUTION_TIME`	`300`	Maximum execution time of scripts (seconds)
`PHP_MAX_INPUT_VARS`	`1000`	Maximum input variables allowed

Error Handling

Variable	Default	Description
`PHP_ERROR_REPORTING`	`E_ALL`	Error reporting level
`PHP_DISPLAY_ERRORS`	`Off`	Display errors in output
`PHP_LOG_ERRORS`	`On`	Log errors to error log

Other Settings

Variable	Default	Description
`PHP_DATE_TIMEZONE`	`UTC`	Default timezone
`PHP_SESSION_GC_MAXLIFETIME`	`1440`	Session garbage collection max lifetime
`PHP_OPCACHE_MAX_ACCELERATED_FILES`	`10000`	OPCache maximum number of files
`PHP_OPCACHE_REVALIDATE_FREQ`	`0`	How often to check script timestamps

Example usage

docker run -e PHP_MEMORY_LIMIT=512M -e PHP_MAX_EXECUTION_TIME=600 kingpin/php-docker:8.3-fpm-alpine-v2

🚀 Quick Start

v1 (Legacy/Compatible)

# Run PHP CLI
docker run --rm kingpin/php-docker:8.3-cli-alpine php -v

# Run with your code mounted
docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.3-cli-alpine php script.php

# Start PHP-FPM server
docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.3-fpm-alpine

v2 (Modern/Supervised)

# Run PHP CLI with s6-overlay
docker run --rm kingpin/php-docker:8.3-cli-alpine-v2 php -v

# Run with your code mounted
docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.3-cli-alpine-v2 php script.php

# Start PHP-FPM with s6 supervision
docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.3-fpm-alpine-v2

v1 vs v2 Comparison

We maintain two image variants to support both existing users and modern use cases:

v1 (Legacy) - Tags without `-v2` suffix

Purpose: Maximum compatibility with existing deployments and stable behavior.

Key Characteristics:

Simpler Dockerfile with fewer runtime layers
No s6-overlay or external init system
Smaller image footprint

Pros:

✅ Drop-in replacement for existing deployments ✅ Simpler container runtime behavior ✅ Smaller learning curve

Cons:

❌ Less robust process supervision
❌ Harder to run multiple services reliably
❌ No built-in service health monitoring
❌ May not handle signals properly in all scenarios

Use v1 when:

You have existing containers relying on legacy behavior
You prefer simpler runtime without init systems
You need maximum backward compatibility
You run single-process containers only

v2 (Modern) - Tags with `-v2` suffix

Purpose: Modernized image with s6-overlay for proper init and service supervision, built on latest Debian Trixie.

Key Characteristics:

Uses s6-overlay as PID 1 init
Proper signal handling and zombie process reaping
Service supervision and restart policies
Built on Debian Trixie (:trixie tags) with :bookworm compatibility aliases

Pros:

✅ Proper PID 1 and process supervision (s6) ✅ Safe for running FPM + sidecar processes (e.g., cron, queue workers) ✅ Environment-based PHP config at runtime ✅ Includes non-root user (appuser, UID 1000) for running your application ✅ Easier to add background services and health checks ✅ Handles container signals properly

The container entrypoint runs as root (required for s6-overlay as PID 1), but a non-root appuser is pre-created. To run your app as this user, use --user 1000:1000 or configure your orchestrator's security context.

Cons:

❌ Slightly larger image due to s6-overlay (~2-3MB) ❌ Different runtime behavior may require minor adjustments ❌ More complex init system to understand

Use v2 when:

You need reliable multi-process containers
You want proper signal handling and process supervision
You're starting a new project
You run background workers or cron alongside FPM

Migration Guide: See docs/migration.md for detailed migration steps and compatibility notes.

Troubleshooting

For common issues and solutions, see docs/troubleshooting.md.

Quick tips:

Container exits immediately: For CLI variants, provide a long-running command
Permission issues: Match container UID with host UID using -u flag
Missing extensions: Extend the image and use install-php-extensions
v2 build fails locally: Enable Docker BuildKit or install buildx plugin
v2 s6-overlay not found: Ensure you're using the -v2 tag

Local Development & Testing

For contributors and advanced users, see docs/local-build.md for:

Using the test-build.sh helper script
Building both v1 and v2 variants locally
Running smoke tests

CI/CD & Publishing

Images are automatically built, tested, and published via GitHub Actions:

All branches/PRs: Build and test only (no publishing)
main branch: Build, test, and publish to all registries

For more details, see docs/ci.md.

Security Considerations

These images are designed with security in mind:

Non-root User (v2): v2 images include a pre-created appuser (UID 1000) for running your application. The entrypoint runs as root for s6-overlay, but your app can run as appuser via --user 1000:1000. v1 images run as the base PHP image default (root)
Limited Permissions (v2): /var/www/html directory has appropriate ownership and permissions
Security Updates: Images are regularly scanned for vulnerabilities via Trivy

Security Best Practices

Never run as root: Keep the default non-root user or specify your own
```
docker run --user 1001:1001 kingpin/php-docker:8.3-fpm-alpine
```

Use read-only volumes when possible

docker run -v $(pwd)/config:/app/config:ro kingpin/php-docker:8.3-cli-alpine

Limit capabilities: Drop unnecessary capabilities

docker run --cap-drop ALL --cap-add NET_BIND_SERVICE kingpin/php-docker:8.3-apache-bookworm

Set memory and CPU limits

docker run --memory="256m" --cpus="0.5" kingpin/php-docker:8.3-fpm-alpine

Use secrets management for sensitive data

docker run --secret db_password kingpin/php-docker:8.3-cli-alpine

Regularly update images to get the latest security patches

Performance Tuning Tips

PHP OPcache Optimization

OPcache is enabled by default. Optimize it further with these settings:

docker run \
  -e PHP_OPCACHE_MEMORY_CONSUMPTION=256 \
  -e PHP_OPCACHE_MAX_ACCELERATED_FILES=20000 \
  -e PHP_OPCACHE_INTERNED_STRINGS_BUFFER=32 \
  kingpin/php-docker:8.3-fpm-alpine

PHP-FPM Tuning (for FPM variants)

For high-traffic applications, consider creating a custom www.conf:

pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500

Memory Optimization

docker run \
  -e PHP_MEMORY_LIMIT=128M \
  kingpin/php-docker:8.3-fpm-alpine

JIT Configuration (PHP 8.0+)

For CPU-intensive applications, enable JIT:

# Add to custom php.ini
opcache.jit_buffer_size=100M
opcache.jit=1255

Additional Performance Tips

Use Alpine-based images for lower memory footprint
Implement proper caching mechanisms (Redis/Memcached)
Consider using PHP 8.3+ for best performance
Use realpath_cache_size and realpath_cache_ttl for applications with many files

📦 Registry Information

These images are available on multiple registries for redundancy and flexibility:

Docker Hub: docker.io/kingpin/php-docker
GitHub Container Registry: ghcr.io/kingpin/php-docker
Quay.io: quay.io/kingpinx1/php-docker

All registries have identical image content and tags.

Available Tags

Tag Format

v1 images: {php-version}-{type}-{os} (e.g., 8.3-fpm-alpine)
v2 images: {php-version}-{type}-{os}-v2 (e.g., 8.3-fpm-alpine-v2)

Current Supported Images

Both v1 and v2 variants are available for all combinations below:

PHP Version	Type	OS	v1 Tag Example	v2 Tag Example
8.4	CLI	Alpine	`8.4-cli-alpine`	`8.4-cli-alpine-v2`
8.4	CLI	Bookworm	`8.4-cli-bookworm`	`8.4-cli-bookworm-v2`
8.4	FPM	Alpine	`8.4-fpm-alpine`	`8.4-fpm-alpine-v2`
8.4	FPM	Bookworm	`8.4-fpm-bookworm`	`8.4-fpm-bookworm-v2`
8.4	Apache	Bookworm	`8.4-apache-bookworm`	`8.4-apache-bookworm-v2`
8.3	CLI	Alpine	`8.3-cli-alpine`	`8.3-cli-alpine-v2`
8.3	CLI	Bookworm	`8.3-cli-bookworm`	`8.3-cli-bookworm-v2`
8.3	FPM	Alpine	`8.3-fpm-alpine`	`8.3-fpm-alpine-v2`
8.3	FPM	Bookworm	`8.3-fpm-bookworm`	`8.3-fpm-bookworm-v2`
8.3	Apache	Bookworm	`8.3-apache-bookworm`	`8.3-apache-bookworm-v2`
8.2	CLI	Alpine	`8.2-cli-alpine`	`8.2-cli-alpine-v2`
8.2	CLI	Bookworm	`8.2-cli-bookworm`	`8.2-cli-bookworm-v2`
8.2	FPM	Alpine	`8.2-fpm-alpine`	`8.2-fpm-alpine-v2`
8.2	FPM	Bookworm	`8.2-fpm-bookworm`	`8.2-fpm-bookworm-v2`
8.2	Apache	Bookworm	`8.2-apache-bookworm`	`8.2-apache-bookworm-v2`

Note: v1 Debian images use Bookworm. v2 Debian images use Trixie, with :bookworm-v2 tags as compatibility aliases pointing to the same Trixie-built images.

Deprecated Tags (v1 only)

The following tags are deprecated and will not be built going forward, but remain available in registries for backwards compatibility:

PHP 7.x:
- 7-cli-bullseye, 7-cli-alpine
- 7-fpm-bullseye, 7-fpm-alpine
- 7-apache-bullseye
PHP 8.0:
- 8-cli-bullseye, 8-cli-alpine
- 8-fpm-bullseye, 8-fpm-alpine
- 8-apache-bullseye
PHP 8.1:
- 8.1-cli-bullseye, 8.1-cli-bookworm, 8.1-cli-alpine
- 8.1-fpm-bullseye, 8.1-fpm-bookworm, 8.1-fpm-alpine
- 8.1-apache-bullseye, 8.1-apache-bookworm

Important: These versions are deprecated. Please upgrade to PHP 8.2, 8.3, or 8.4 for security and performance.

📊 Image Sizes

Approximate compressed sizes (vary by PHP version and platform):

Type	OS	v1 Size	v2 Size
CLI	Alpine	~80MB	~83MB
CLI	Bookworm	~140MB	~143MB
FPM	Alpine	~85MB	~88MB
FPM	Bookworm	~150MB	~153MB
Apache	Bookworm	~180MB	~183MB

v2 overhead is primarily the s6-overlay binaries (~2-3MB). Build dependencies are cleaned up to minimize image size.

Pre-installed PHP Extensions

Web Development

json
mysqli
pdo_mysql
pdo_pgsql
pgsql
soap
sockets

Image Processing

gd (no AV1 encoder on ARM7)
imagick
exif
vips

Performance & Caching

opcache
redis
memcached
zstd

File Operations

Utility Extensions

amqp
bcmath
calendar
ctype
intl
imap
ldap
mbstring
mcrypt
mongodb
snmp
tidy
timezonedb
uuid
xsl
yaml

Usage Examples

Basic usage with Docker

docker run -d --name php-app kingpin/php-docker:8.3-cli-alpine php -v

With Docker Compose

services:
  php-fpm:
    image: kingpin/php-docker:8.3-fpm-alpine
    volumes:
      - ./src:/var/www/html
    networks:
      - app-network

  webserver:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./src:/var/www/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    networks:
      - app-network

networks:
  app-network:

WordPress setup guide

For detailed WordPress setup instructions, visit our guide.

Building Custom Images

You can build custom images based on these by extending the Dockerfile:

FROM kingpin/php-docker:8.3-fpm-alpine

# Add your custom configurations
COPY custom-php.ini /usr/local/etc/php/conf.d/

# Install additional extensions if needed
RUN install-php-extensions swoole

Deprecated Versions

The following PHP versions are no longer actively built but remain available in registries for backwards compatibility:

PHP 7.x (End of Life)

All PHP 7.x images (7.4 and earlier)
Last published: January 2025
Available tags: 7-cli-alpine, 7-fpm-alpine, 7-apache-bullseye, etc.

PHP 8.1 (End of Active Support)

All PHP 8.1 images
Last published: January 2025
Available tags: 8.1-cli-alpine, 8.1-fpm-alpine, 8.1-apache-bookworm, etc.

Migration Path:

Upgrade to PHP 8.2 or 8.3 for continued security updates and new builds
See migration guide for upgrade assistance
Existing images will remain available in Docker Hub, GHCR, and Quay.io

🏗️ Architecture Diagram

                  ┌───────────────┐
                  │   Base Image  │
                  │  php:X.Y-...  │
                  └───────┬───────┘
                          │
            ┌─────────────┴─────────────┐
            │                           │
     ┌──────▼──────┐            ┌───────▼───────┐
     │     v1      │            │      v2       │
     │  (simple)   │            │ (s6-overlay)  │
     └──────┬──────┘            └───────┬───────┘
            │                           │
    ┌───────┼───────┐          ┌────────┼────────┐
    │               │          │                 │
 Alpine        Bookworm     Alpine           Trixie
    │               │          │            (bookworm
    │               │          │             compat)
    └───────┬───────┘          └────────┬────────┘
            │                           │
            └─────────┬─────────────────┘
                      │
           ┌──────────┼──────────┐
           │          │          │
    ┌──────▼───┐ ┌────▼────┐ ┌───▼─────┐
    │   CLI    │ │   FPM   │ │  Apache │
    └──────────┘ └─────────┘ └─────────┘

Contributing

We welcome contributions to improve these Docker images!

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/new-extension
Make your changes (update both Dockerfile.v1 and Dockerfile.v2 if applicable)
Test locally: Use test-build.sh to verify builds
Submit a Pull Request

Guidelines

Follow the existing code style and conventions
Test both v1 and v2 variants when making changes
Update documentation as needed
Keep PRs focused on a single change
Reference issues in commit messages

Our CI/CD pipeline will automatically test your changes when you submit a PR.

License

This project is licensed under the MIT License - see LICENSE for details.

Need help? Open an issue or check our troubleshooting guide.

Uh oh!

FilesExpand file tree

README.md

Latest commit

History