PHP CLI Image

Production-grade Docker image for PHP CLI applications: workers, cron jobs, Kafka consumers, deployment scripts. Multi-arch, 20+ extensions, OPcache + JIT, runtime configuration via ENV.

Overview

headgent/phpcli is a multi-stage Alpine image for all PHP processes that don't need a web server. The image includes a complete extension stack (database, messaging, caching, media) and can be configured via 30+ environment variables without rebuilding.

GitHub: jardisOps/phpcli

Property	Value
PHP versions	8.2, 8.3, 8.4
Architectures	linux/amd64, linux/arm64
Image size	~142–148 MB (compressed)
Base	Alpine 3.23
Composer	2.9.5 (pinned)

Installation

docker pull headgent/phpcli:8.4

Available tags: 8.2, 8.3, 8.4, latest (= 8.4).

Quick Start

# docker-compose.yml
services:
  worker:
    image: headgent/phpcli:8.4
    volumes:
      - ./:/app
    environment:
      PHP_MEMORY_LIMIT: 256M
      XDEBUG_MODE: "off"
    command: php /app/bin/worker.php

Extensions

Database

Extension	Type	Description
pdo	Built-in	PDO abstraction
pdo_mysql	Built-in	MySQL / MariaDB
mysqli	Built-in	MySQL (procedural)
pdo_pgsql	Built-in	PostgreSQL

Messaging & Caching

Extension	Type	Version	Description
amqp	PECL	2.2.0	RabbitMQ AMQP 0-9-1
rdkafka	PECL	6.0.5	Apache Kafka client
apcu	PECL	5.1.28	In-memory user cache
redis	PECL	6.3.0	Redis client
opcache	Built-in	—	Bytecode cache + JIT

Web, I/O & Data

Extension	Type	Description
curl	Built-in	HTTP client
soap	Built-in	SOAP web services
sockets	Built-in	Network sockets
dom	Built-in	XML processing
zip	Built-in	Archive manipulation
mbstring	Built-in	Multi-byte strings
intl	Built-in	Internationalization
bcmath	Built-in	Arbitrary precision math

Media & Processes

Extension	Type	Description
gd	Built-in	Image generation (FreeType + JPEG)
exif	Built-in	Image metadata
pcntl	Built-in	Process control (signals)

Debugging & Coverage

Extension	Type	Version	Description
xdebug	PECL	3.5.1	Step debugging + profiling
pcov	PECL	1.0.12	Fast code coverage

Configuration

All values are configurable via environment variables, no rebuild required.

PHP Core

Variable	Default	Description
PHP_MEMORY_LIMIT	512M	Memory limit
PHP_MAX_EXECUTION_TIME	0	Max execution time (0 = unlimited)
PHP_TIMEZONE	UTC	Timezone
PHP_ERROR_REPORTING	E_ALL & ~E_DEPRECATED & ~E_STRICT	Error reporting level
PHP_DISPLAY_ERRORS	Off	Display errors
PHP_LOG_ERRORS	On	Log errors

OPcache & JIT

Variable	Default	Description
OPCACHE_MEMORY_CONSUMPTION	128	OPcache memory (MB)
OPCACHE_MAX_ACCELERATED_FILES	4000	Max cached files
OPCACHE_REVALIDATE_FREQ	2	Revalidation interval (seconds)
OPCACHE_JIT	1254	JIT mode (tracing)
OPCACHE_JIT_BUFFER_SIZE	128M	JIT buffer

APCu

Variable	Default	Description
APCU_SHM_SIZE	64M	Shared memory size

Xdebug

Variable	Default	Description
XDEBUG_MODE	debug	Mode (off, debug, profile, trace, coverage)
XDEBUG_START_WITH_REQUEST	yes	Auto-start
XDEBUG_CLIENT_HOST	host.docker.internal	IDE host
XDEBUG_CLIENT_PORT	9003	IDE port
XDEBUG_LOG_LEVEL	0	Log level (0–10)

PCOV

Variable	Default	Description
PCOV_ENABLED	0	Enable coverage (0/1)

PCOV vs. Xdebug

When PCOV_ENABLED=1 is set, the entrypoint script automatically disables Xdebug (XDEBUG_MODE=off). PCOV is ~2× faster than Xdebug for code coverage.

Security

• Non-root execution — container starts as root for UID/GID adaptation, then drops to appuser
• Automatic UID/GID adaptation — detects mounted /app volume owner and adapts appuser
• expose_php = Off — PHP version not exposed in HTTP headers
• Health check — validates PHP and Composer

Build Arguments

For custom builds, these arguments can be passed at build time:

Argument	Default	Description
PHP_VERSION	8.3	PHP version
ALPINE_VERSION	3.23	Alpine base
COMPOSER_VERSION	2.9.5	Composer version
PUID / PGID	1000	User/group ID
INSTALL_DB_CLIENTS	(empty)	DB clients: mysql,postgres,sqlite
APCU_VERSION	5.1.28	PECL version
REDIS_VERSION	6.3.0	PECL version
XDEBUG_VERSION	3.5.1	PECL version
PCOV_VERSION	1.0.12	PECL version
AMQP_VERSION	2.2.0	PECL version
RDKAFKA_VERSION	6.0.5	PECL version

Makefile

Target	Description
make build	Local build for current PHP_VERSION
make build-all	Build all PHP versions locally
make build-remote-all	Build all versions multi-arch and push
make build-remote-version	Build one version multi-arch and push
make test-all	Run all tests on both architectures
make test-extensions	Verify extensions on both architectures
make test-opcache	Verify OPcache + JIT
make shell	Interactive shell in container
make clean	Clean up containers, images and cache
make info	Show current build configuration

Use Cases

• Laravel/Symfony workers — queue consumers, scheduled commands
• Kafka/RabbitMQ consumers — event-driven microservices
• Cron jobs — scheduled tasks in containers
• Deployment scripts — migrations, seed data, cache warmup
• CI/CD — test runner with PCOV for fast coverage