Docker PHP Extensions Knowledge Base

Patterns for installing, building, and managing PHP extensions in Docker containers.

Extension Categories

Installation Methods

Method 1: docker-php-ext-install (Built-in Extensions)

# Extensions bundled with PHP source
RUN docker-php-ext-install -j$(nproc) \
    opcache \
    intl \
    pdo_pgsql \
    pdo_mysql \
    zip \
    bcmath \
    pcntl \
    sockets

Method 2: docker-php-ext-configure + install

# Extensions requiring configuration
RUN docker-php-ext-configure gd \
        --with-freetype \
        --with-jpeg \
        --with-webp \
    && docker-php-ext-install -j$(nproc) gd

Method 3: PECL Install

# Extensions from PECL repository
RUN pecl install redis-6.1.0 apcu-5.1.24 igbinary-3.2.16 \
    && docker-php-ext-enable redis apcu igbinary

Method 4: Manual Compilation

# For extensions not in PECL or needing custom patches
RUN curl -fsSL https://github.com/example/ext/archive/v1.0.tar.gz | tar xz \
    && cd ext-1.0 \
    && phpize \
    && ./configure \
    && make -j$(nproc) \
    && make install \
    && docker-php-ext-enable ext

Alpine vs Debian Build Dependencies

Runtime vs Build Dependencies Pattern

FROM php:8.4-fpm-alpine AS production

# 1. Install build dependencies (virtual package for easy removal)
RUN apk add --no-cache --virtual .build-deps \
        $PHPIZE_DEPS \
        icu-dev \
        libpq-dev \
        libzip-dev \
        freetype-dev \
        libjpeg-turbo-dev \
        libpng-dev \
        rabbitmq-c-dev \
    \
# 2. Install and configure extensions
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
        intl \
        pdo_pgsql \
        zip \
        gd \
        opcache \
        bcmath \
        pcntl \
        sockets \
    \
# 3. Install PECL extensions
    && pecl install redis apcu amqp igbinary \
    && docker-php-ext-enable redis apcu amqp igbinary \
    \
# 4. Remove build dependencies (keep runtime libs)
    && apk del .build-deps

# 5. Install runtime-only libraries
RUN apk add --no-cache \
    icu-libs \
    libpq \
    libzip \
    freetype \
    libjpeg-turbo \
    libpng \
    rabbitmq-c

Extension Builder Stage Pattern

# Dedicated stage for compiling extensions (reusable across images)
FROM php:8.4-fpm-alpine AS ext-builder

RUN apk add --no-cache --virtual .build-deps \
        $PHPIZE_DEPS \
        icu-dev \
        libpq-dev \
        libzip-dev \
    && docker-php-ext-install -j$(nproc) intl pdo_pgsql zip opcache bcmath \
    && pecl install redis apcu \
    && docker-php-ext-enable redis apcu \
    && apk del .build-deps

# Production stage copies only compiled artifacts
FROM php:8.4-fpm-alpine AS production

COPY --from=ext-builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/
COPY --from=ext-builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/

RUN apk add --no-cache icu-libs libpq libzip

Framework Extension Combinations

Symfony Stack

RUN docker-php-ext-install -j$(nproc) \
    intl \           # Translation, validation, routing
    pdo_pgsql \      # Doctrine DBAL (PostgreSQL)
    opcache \        # Performance
    zip \            # Composer, file handling
    bcmath \         # Precise math (money)
    pcntl \          # Messenger async workers
    sockets          # Messenger AMQP transport

RUN pecl install redis apcu amqp \
    && docker-php-ext-enable redis apcu amqp

Laravel Stack

RUN docker-php-ext-install -j$(nproc) \
    pdo_mysql \      # Eloquent (MySQL)
    opcache \        # Performance
    zip \            # File handling
    bcmath \         # Precise math
    pcntl \          # Horizon workers
    exif             # Image metadata

RUN pecl install redis igbinary \
    && docker-php-ext-enable redis igbinary

API Platform / High-Load

RUN docker-php-ext-install -j$(nproc) \
    intl \
    pdo_pgsql \
    opcache \
    bcmath \
    pcntl \
    sockets

RUN pecl install redis apcu amqp igbinary msgpack \
    && docker-php-ext-enable redis apcu amqp igbinary msgpack

OPcache Configuration for Production

; /usr/local/etc/php/conf.d/opcache.ini
opcache.enable=1
opcache.enable_cli=0
opcache.memory_consumption=256
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
opcache.save_comments=1
opcache.jit=tracing
opcache.jit_buffer_size=128M

COPY docker/php/opcache.ini /usr/local/etc/php/conf.d/opcache.ini

Troubleshooting

References

For the full extensions matrix with all dependencies, see references/extensions-matrix.md. For base image selection, see docker-base-images-knowledge.