Available Extensions

Complete reference of all PHP extensions included in Cbox PHP Base Images by tier.

Extension Overview by Tier

Cbox images come in four tiers with different extension sets:

Slim Tier Extensions

The Slim tier includes all core extensions needed for most PHP applications.

PHP Extensions

Standard Tier Additions

These extensions are added in the standard tier (and inherited by chromium/dev):

Tools Included

Standard Tier Extensions

The Standard tier includes everything in Slim, plus image processing, Node.js, and Bun.

Additional Extensions (on top of Slim)

Additional Tools

Image Format Support (Standard Tier)

Chromium Tier Extensions

The Chromium tier includes everything in Standard, plus Chromium for browser automation.

Additional Components (on top of Standard)

Environment Variables (auto-set)

PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Dev Tier Extensions

The Dev tier includes everything in Chromium, plus development and profiling tools.

Additional Extensions (on top of Chromium)

Xdebug Configuration

The dev tier includes pre-configured Xdebug settings:

xdebug.mode=develop,debug,coverage
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=trigger
xdebug.discover_client_host=true
xdebug.log=/tmp/xdebug.log
xdebug.idekey=VSCODE

Xdebug Modes:

• off - Disabled
• develop - Development helpers (var_dump improvements)
• coverage - Code coverage collection
• debug - Step debugging
• gcstats - Garbage collection statistics
• profile - Profiling
• trace - Function tracing

PCOV Configuration

PCOV is disabled by default (for faster execution). Enable it when running tests:

pcov.enabled=0
pcov.directory=/var/www/html

Usage:

# Enable PCOV for PHPUnit coverage
php -d pcov.enabled=1 vendor/bin/phpunit --coverage-text

SPX Profiler

SPX provides a web-based UI for profiling:

spx.http_enabled=1
spx.http_key=dev
spx.http_ip_whitelist=*

Access the SPX UI:

http://your-app/?SPX_KEY=dev&SPX_UI_URI=/

Dev Tier Best Practices

1. Use PCOV for CI coverage - It's 10x faster than Xdebug coverage
2. Disable Xdebug in production - Dev tier is NOT for production
3. Use SPX for performance profiling - More visual than Xdebug profiler
4. Switch modes as needed - Only enable what you need

# Fast coverage in CI
docker run --rm -e XDEBUG_MODE=off \
  -v $(pwd):/var/www/html \
  ghcr.io/cboxdk/php-baseimages/php-fpm:8.5-bookworm-dev-v1 \
  php -d pcov.enabled=1 vendor/bin/phpunit --coverage-text

# Step debugging
docker run --rm -e XDEBUG_MODE=debug \
  ghcr.io/cboxdk/php-baseimages/php-fpm:8.5-bookworm-dev-v1 \
  php artisan test

Extension Comparison by Tier

* opentelemetry is installed but not loaded by default. Loading it enables the Zend observer API, which taxes every PHP function call even with no OTel SDK installed - measured at -18.5% throughput on a Laravel app (0% on tight-loop code) on dedicated hardware. Set PHP_OPENTELEMETRY=true to load it; the entrypoint appends the extension's scan dir to PHP_INI_SCAN_DIR, so it works on read-only filesystems too.

If the goal is telemetry from a Laravel app rather than C-level auto-instrumentation, cboxdk/laravel-telemetry collects it in userland through the framework's own extension points - it does not enable the observer API, so it carries none of this tax.

† cbox_telemetry (cboxdk/telemetry-native) is likewise installed but not loaded by default, for a different reason: it is pre-1.0, and it installs fatal-signal handlers for its crash recorder. That is not something an image should arm on every application that pulls the tag. Its own measurements put loading it inside the noise floor of an FPM harness - the gate here is about maturity, not about a measured tax. Set PHP_TELEMETRY_NATIVE=true to load it. Absent from the PHP 8.2 images: the extension supports 8.3+ only.

See Runtime telemetry below.

Runtime telemetry (cbox_telemetry)

cboxdk/telemetry-native is the native half of cboxdk/laravel-telemetry. The Laravel package keeps owning everything semantic - trace context, sampling policy, redaction, attribute naming, OTLP export. The extension only observes the PHP runtime, and answers the questions the userland package structurally cannot:

• Which call stacks burned the CPU - a statistical CPU profiler sampling on a per-thread CPU timer, not wall clock
• Why the connection took 180 ms - native timing around PDO::__construct, PDO::connect, Redis::connect/pconnect and curl_exec
• What the process was doing when it died - a signal-safe crash recorder that writes one fixed-width record, then re-raises so the process dies exactly as it would have, core dump and all

It ships in every tier from slim up, on PHP 8.3 and newer, and it is off until you turn it on:

services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm-v1
    environment:
      PHP_TELEMETRY_NATIVE: "true"
      # FPM only - see the warning below
      PHP_TELEMETRY_NATIVE_AUTO: "true"

Verify what you got:

docker compose exec app php -r 'print_r(cbox_telemetry_status());'

The two fields worth reading: timer_backend must say posix-thread-cputime (anything else means samples measure wall time), and hook_detail reports requested versus installed per hook group - which is how you find out that redis.connect timings are missing because ext-redis is not in the image, rather than because the hook is off.

PHP_TELEMETRY_NATIVE_AUTO is for FPM, not for workers

Automatic units open at RINIT, before any PHP runs, so a profile covers framework boot instead of starting wherever your middleware does - on a cold request that is often most of the time.

In a queue worker or an Octane server, RINIT fires once for the whole process. An automatic unit there would span hours and mean nothing. Leave the switch off in those containers and let the consumer call begin()/finish() per job. That is why it is a separate variable rather than something PHP_TELEMETRY_NATIVE=true implies.

Why it is opt-in

Unlike opentelemetry, this is not a performance gate. Upstream's FPM measurements put loading the extension, installing the hooks and arming the crash recorder inside the noise floor of the harness, and profiling every request at 1 ms somewhere between nothing and about 5%.

It is off because it is pre-1.0 and because the crash recorder installs handlers for fatal signals. Arming those on every application that happens to pull a rolling tag is a decision for the application, not for the image. That calculus changes at 1.0; the variable will not.

Crash records and read-only filesystems

The recorder writes to cbox_telemetry.crash.dir (default /tmp/cbox-telemetry, with a private 0700 subdirectory per uid). On a container with a read-only root filesystem, mount a writable /tmp - otherwise cbox_telemetry_status() reports crash_recorder => unavailable: directory and records nothing. It says so truthfully; it does not fail the request.

Extension Versions

All PECL extensions use pinned versions for reproducibility:

Checking Installed Extensions

List All Extensions

# In running container
docker exec myapp php -m

# One-liner
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-v1 php -m

Check Specific Extension

# Check if redis is loaded
docker exec myapp php -m | grep redis

# Get extension version
docker exec myapp php -r "echo phpversion('redis');"

Full Extension Info

# Detailed extension information
docker exec myapp php -i | grep -A 10 "redis"

Adding Extensions

PECL Extensions

FROM ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-v1

# Install PECL extension
RUN apt-get update && apt-get install -y $PHPIZE_DEPS && \
    pecl install swoole && \
    docker-php-ext-enable swoole && \
    apt-get purge -y --auto-remove $PHPIZE_DEPS && rm -rf /var/lib/apt/lists/*

Core Extensions

FROM ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-v1

# Enable a disabled core extension
RUN docker-php-ext-install shmop

System Dependencies

Some extensions require system packages:

FROM ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-v1

# Example: Adding additional libraries
RUN apt-get update && apt-get install -y some-package-dev && \
    docker-php-ext-install some-extension

Framework Requirements

Laravel

All Laravel requirements are satisfied by Slim tier:

Symfony

All Symfony requirements are satisfied by Slim tier:

WordPress

All WordPress requirements are satisfied by Standard tier (for ImageMagick):

Browsershot / Laravel Dusk

Requires Chromium tier for Chromium:

Troubleshooting

Extension Not Loading

# Check PHP error log
docker exec myapp cat /var/log/php/error.log

# Verify extension file exists
docker exec myapp ls /usr/local/lib/php/extensions/

Missing System Dependency

# Check for missing libraries
docker exec myapp ldd /usr/local/lib/php/extensions/*/redis.so

Version Conflicts

# Check loaded extension versions
docker exec myapp php -r "foreach(get_loaded_extensions() as \$ext) echo \$ext.': '.phpversion(\$ext).PHP_EOL;"

Need a specific extension? See Extending Images | Choosing Your Image