PHP Extension Requirements and Limits
Winter Boot relies on a small set of PHP extensions. This page lists what each one is needed for and what happens when it is missing or misconfigured. The startup banner prints the detected version (or not installed) of Swoole, rdkafka, and redis on every boot — check it first when something extension-related misbehaves.
Need anything else (for example memcache or opentelemetry)? Extend the image with your own multi-stage build rather than installing into it — that keeps the runtime image small. See the Dockerfile for the builder pattern to follow.
The sections below matter mostly for setups that do not use this image.
Swoole (required for server, async and coroutines)
Section titled “Swoole (required for server, async and coroutines)”Web applications run on the Swoole server (WinterWebSwooleApplication), and all concurrency features build on it.
- Async and scheduling refuse to boot without it. Using
#[EnableAsync],#[EnableScheduling],#[Async]or#[Scheduled]without the extension throws anAnnotationExceptionduring startup naming the offending class or method. There is no silent fallback — remove the annotation or install Swoole. - Daemon threads need it.
#[DaemonThread]workers are Swoole processes; without the extension they cannot start. - Never read request state from superglobals. Under Swoole, worker processes are shared across requests:
$_SERVER,$_COOKIEand thesession_*functions can carry values belonging to another request. Always read through the injectedHttpRequest(getQueryParam(),getCookie(),getFirstHeader(), …) and manage sessions viaSessionManager. - Graceful degradation where it is safe. Coroutine-scoped connection pools and request detection quietly fall back to non-coroutine behavior when Swoole (or its
Coroutine/Channelclasses) is unavailable — pooling still works, just without coroutine isolation.
winter_boot (required since 2.1.0, native capabilities)
Section titled “winter_boot (required since 2.1.0, native capabilities)”The bundled native extension. Booting without it stops the application with a clear error — use the runtime Docker image, where it is preinstalled, instead of assembling it yourself. See Native Extension for details; the limits in brief:
- Native AOP advises the original bean methods (no proxies): a
stopExecution()value must match the declared return type exactly,staticmethods cannot carry advice, and an explicitparent::call to an advised method runs its advice. - Loading the extension disables PHP’s JIT compiler automatically (the engine does this for any executor override); OPcache itself keeps working. There is no flag to override this — size the performance expectations accordingly.
- Do not load Xdebug alongside
winter_bootin Swoole server environments: Swoole workers can crash (segfault) when Xdebug’s develop mode formats a thrown exception. Remove the Xdebug ini or setxdebug.mode=off. The runtime Docker image ships without Xdebug.
APCu (optional, ApcCache only)
Section titled “APCu (optional, ApcCache only)”ApcCache::isEnabled()returnsfalseunless the extension is both loaded and enabled. Callers must check it first: thecache()path calls the APCu functions directly, so skipping the check without APCu fails instead of degrading.- Swoole servers run under the CLI SAPI, where APCu is off by default (
apc.enable_cli=0), soisEnabled()isfalsein Swoole workers, console commands and migrations unlessapc.enable_cli=1is set. The runtime Docker image sets it. Each process has its own APCu memory: workers of one Swoole server share it, but a separate console or migration run does not, so never use APCu as cross-process state.
OpenTelemetry (optional, telemetry module)
Section titled “OpenTelemetry (optional, telemetry module)”- Enabling
OpenTelemetryModulewithout the extension fails fast: module startup throwsMissingExtensionException. - The extension alone is not enough — telemetry also needs the OpenTelemetry SDK and an exporter package, configured through the standard
OTEL_*environment variables (see Telemetry). When spans go missing, checkOTEL_PHP_AUTOLOAD_ENABLEDand the exporter endpoint first.
redis / memcache / rdkafka (only with their modules)
Section titled “redis / memcache / rdkafka (only with their modules)”These matter only when the corresponding module or backend is enabled; the core framework never requires them.
- redis (phpredis): needed for the Redis module (
PhpRedisTemplate, cluster template),RedisCache, and the async Redis queue store. - memcache / memcached: needed for the Memcache module templates. The two extensions are different client libraries — enable the one matching the configured template.
- rdkafka (plus Swoole): needed for the Kafka module (producers/consumers) and the Kafka-backed DTCE queue. Without both, Kafka consumers and workers cannot start.
The runtime Docker image preinstalls redis, rdkafka, swoole and apcu (with pcntl, curl, zip, PostgreSQL drivers); memcache(d) and opentelemetry are added only when the application needs them.