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.

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.

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

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.

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

# 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

# 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

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

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

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.

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

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

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.

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

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

2. Use read-only volumes when possible

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

3. Limit capabilities: Drop unnecessary capabilities

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

4. Set memory and CPU limits

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

5. Use secrets management for sensitive data

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

6. Regularly update images to get the latest security patches

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

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

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

For CPU-intensive applications, enable JIT:

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

• 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

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.

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

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

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.

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.

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

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

• json
• mysqli
• pdo_mysql
• pdo_pgsql
• pgsql
• soap
• sockets

• gd (no AV1 encoder on ARM7)
• imagick
• exif
• vips

• opcache
• redis
• memcached
• zstd

• zip
• bz2

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

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

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:

For detailed WordPress setup instructions, visit our guide.

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

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

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

• 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

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

We welcome contributions to improve these Docker images!

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

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

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

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