Extension Limits

Winter Boot leans on a small set of PHP extensions. This page lists what each one is needed for and, more importantly, what happens when it is absent or misconfigured — so a missing extension shows up as an understood error, not a mystery. The startup banner prints the detected version (or not installed) for Swoole, rdkafka and redis on every boot; check it first when something extension-related misbehaves.

Tip

Skip this entire page: run the suvera/winter-boot runtime Docker image instead of assembling extensions yourself. It preinstalls and enables Swoole, redis, rdkafka and winter_boot (plus pcntl, curl, zip and PostgreSQL drivers), so none of the missing-extension failures below can occur.

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 then apply only to setups that do not use this image.

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 an AnnotationException during 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, $_COOKIE and the session_* functions can carry values belonging to another request. Always read through the injected HttpRequest (getQueryParam(), getCookie(), getFirstHeader(), …) and manage sessions via SessionManager.
• 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/Channel classes) is unavailable — pooling still works, just without coroutine isolation.

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 full usage; the limits in brief:

• Throws Error outside a function body (global/file/eval scope) and inside generator functions (use try/finally there instead).
• Throws TypeError for a non-callable argument.
• Fully supported inside fibers; Fiber::suspend() never triggers callbacks.
• Pending callbacks are discarded — never executed — on fatal errors (E_ERROR, out of memory) and when a fiber is destroyed while suspended.
• defered() (one r) is an accepted alias with identical behavior.
• Native AOP advises the original bean methods (no proxies): a stopExecution() value must match the declared return type exactly, static methods cannot carry advice, and an explicit parent:: 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_boot in Swoole server environments. Any executor override (proven with a 20-line passthrough extension, so this is not specific to winter_boot) segfaults Swoole workers when Xdebug’s develop-mode exception hook formats a thrown exception. Either remove the Xdebug ini or set xdebug.mode=off. The runtime Docker image ships without Xdebug, so deployments are unaffected.

Note

Unlike a global defer() name, deferred() coexists peacefully with Swoole — both extensions stay enabled in the runtime image.

APCu (optional, ApcCache only)

• ApcCache::isEnabled() returns false unless the extension is both loaded and enabled. Callers must check it first: the cache() path calls the APCu functions directly, so skipping the check without APCu fails instead of degrading.
• APCu is commonly disabled under CLI (apc.enable_cli), so isEnabled() can be false in console and migration runs even when web workers cache fine. Do not assume CLI and Swoole workers see the same cache state.

OpenTelemetry (optional, telemetry module)

• Enabling OpenTelemetryModule without the extension fails fast: module startup throws MissingExtensionException.
• The extension alone is not enough — telemetry also needs the OpenTelemetry SDK, the SPI plugin bridge, and an opentelemetry.yaml config wired through the module entry. When spans go missing, check exporter endpoint and sampler settings in that config next.

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, Redis-backed locks and the async Redis queue store. Both redis and swoole back the async paths.
• 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 and swoole (with pcntl, curl, zip, PostgreSQL drivers); memcache(d) and opentelemetry are added only when the application needs them.