Skip to content

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 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)

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, 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: Swoole workers can crash (segfault) when Xdebug’s develop mode formats a thrown exception. Remove the Xdebug ini or set xdebug.mode=off. The runtime Docker image ships without Xdebug.
  • 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.
  • Swoole servers run under the CLI SAPI, where APCu is off by default (apc.enable_cli=0), so isEnabled() is false in Swoole workers, console commands and migrations unless apc.enable_cli=1 is 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 OpenTelemetryModule without the extension fails fast: module startup throws MissingExtensionException.
  • 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, check OTEL_PHP_AUTOLOAD_ENABLED and 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.