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.5-fpm-alpine-v2)
Existing deployments or maximum compatibility? → Use v1 images (e.g., 8.5-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, 8.4, and 8.5 (actively built); PHP 7.x, 8.0, and 8.1 deprecated. PHP 8.2 is scheduled for removal after 2026-12-31 when upstream security support ends — see deprecation schedule.
• 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.5-fpm-alpine-v2

🚀 Quick Start

v1 (Legacy/Compatible)

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

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

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

v2 (Modern/Supervised)

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

# Run with your code mounted
docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.5-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.5-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

1. Never run as root: Keep the default non-root user or specify your own

   docker run --user 1001:1001 kingpin/php-docker:8.5-fpm-alpine

2. Use read-only volumes when possible

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

3. Limit capabilities: Drop unnecessary capabilities

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

4. Set memory and CPU limits

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

5. Use secrets management for sensitive data

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

6. 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.5-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.5-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.5-fpm-alpine)
• v2 images: {php-version}-{type}-{os}-v2 (e.g., 8.5-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.5	CLI	Alpine	8.5-cli-alpine	8.5-cli-alpine-v2
8.5	CLI	Bookworm	8.5-cli-bookworm	8.5-cli-bookworm-v2
8.5	FPM	Alpine	8.5-fpm-alpine	8.5-fpm-alpine-v2
8.5	FPM	Bookworm	8.5-fpm-bookworm	8.5-fpm-bookworm-v2
8.5	Apache	Bookworm	8.5-apache-bookworm	8.5-apache-bookworm-v2
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.

Deprecation Schedule

PHP versions are removed from the build matrix when upstream security support ends (php.net schedule). Existing image tags remain pullable from registries indefinitely; only new builds stop.

Version	Upstream security ends	Planned removal
8.2	2026-12-31	After 2026-12-31
8.3	2027-12-31	After 2027-12-31
8.4	2028-12-31	After 2028-12-31
8.5	2029-12-31	After 2029-12-31

If you're pinned to a 8.2-* tag, plan to bump to 8.3 or newer before the end of 2026.

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 an actively-supported PHP version (8.2–8.5) 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

• zip
• bz2

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.5-cli-alpine php -v

With Docker Compose

services:
  php-fpm:
    image: kingpin/php-docker:8.5-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.5-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 an actively-supported PHP version (8.2–8.5) 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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-extension
3. Make your changes (update both Dockerfile.v1 and Dockerfile.v2 if applicable)
4. Test locally: Use test-build.sh to verify builds
5. 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.