How to upgrade to OpenSwoole 26.x from 22.x/25.x

Latest version: pecl install openswoole-26.11.0 | composer require openswoole/core:26.11.0

Upgrading to 26.11

PHP 8.6 support

OpenSwoole 26.11 supports PHP 8.3, 8.4, 8.5 and 8.6. It is the last release series to support PHP 8.3; OpenSwoole 27.2 will require PHP 8.4 or later. Plan an upgrade to PHP 8.4+ if you are on PHP 8.3.

Hooked ssl:// and tls:// streams verify the peer

Hooked ssl:// and tls:// client streams now verify the peer like native PHP: verify_peer and verify_peer_name are true and allow_self_signed is false by default, and the TLS host name is taken from the host in the address.

Connections to servers with a self-signed or invalid certificate now fail. Trust the CA with cafile, or turn the checks off in the stream context:

$context = stream_context_create(['ssl' => ['verify_peer' => false, 'verify_peer_name' => false]]);
$fp = stream_socket_client('ssl://127.0.0.1:9501', $errno, $errstr, 5, STREAM_CLIENT_CONNECT, $context);

See HOOK_SSL.

Cookie values are now raw url encoded and decoded: a + stays a + and a space is %20. This applies to $request->cookie, Response::cookie() and the coroutine HTTP clients. When a cookie name is sent twice, the first value is used.

Cookies containing spaces that were set by an earlier version were sent with + and read back with + until they are set again. If your application stores spaces in cookies, set those cookies again after upgrading.

Response::cookie() sends Max-Age

Response::cookie() now sends Max-Age next to expires when an expiry time is set, and Max-Age=0 when a cookie is deleted, like PHP's setcookie(). No change is needed.

io_uring fallback and reactor_type in Server::set()

When io_uring cannot be set up, for example in Docker with the default seccomp profile or when kernel.io_uring_disabled is set, the io_uring reactor falls back to epoll with one warning and the io_uring file engine falls back to the thread pool quietly. reactor_type can now be set with $server->set(). Multishot poll needs kernel 5.13+; older kernels use single-shot poll automatically.

HTTP2 server settings

http2_header_table_size, http2_initial_window_size, http2_max_concurrent_streams, http2_max_frame_size and http2_max_header_list_size were ignored before 26.11. They are now applied and sent to clients, so clients follow them too. Check the values in your $server->set() call.

Native curl hook

CURLOPT_PREREQFUNCTION (PHP 8.4+, used by Guzzle 7.12+) and CURLOPT_SEEKFUNCTION (PHP 8.6) now work with HOOK_NATIVE_CURL.

PIE

OpenSwoole can be installed with PIE:

pie install openswoole/ext-openswoole

PHP 8.3 minimum requirement

OpenSwoole 26.x requires PHP 8.3 or above. PHP 8.2 support has been dropped. PHP 8.5 is fully supported, and PHP 8.6 is supported since OpenSwoole 26.11.0.

New coroutine context: PHP native Fiber

OpenSwoole 26.x introduces a new coroutine context backend using PHP's native zend_fiber API. This replaces the Boost ASM or ucontext backends and enables proper integration with Xdebug, profilers, and fiber-aware extensions.

Enable it at runtime:

Co::set(['use_fiber_context' => true]);

Or via INI:

openswoole.use_fiber_context=On

Xdebug step debugging inside coroutines

When the fiber context is enabled, Xdebug step debugging now works correctly inside coroutines. The legacy "extremely dangerous" warning has been removed.

Runtime reactor type selection

You can now select the event reactor backend at runtime instead of at compile time:

Co::set(['reactor_type' => OPENSWOOLE_IO_URING]);

Available constants:

  • OPENSWOOLE_EPOLL (Linux default)
  • OPENSWOOLE_KQUEUE (macOS/BSD default)
  • OPENSWOOLE_POLL
  • OPENSWOOLE_SELECT
  • OPENSWOOLE_IO_URING (Linux, requires liburing and --enable-io-uring)

Reactor type constants are no longer guarded by compile-time checks; runtime validation handles unsupported backends.

io_uring reactor and async file I/O

OpenSwoole 26.x adds a new io_uring-based event reactor and async file I/O engine on Linux:

  • Reactor: Uses IORING_OP_POLL_ADD as a drop-in replacement for epoll. Supports multishot poll on kernel 5.13+.
  • File I/O: Dedicated io_uring ring for async file operations (open, read, write, fstat, fsync, unlink, rename, mkdir, rmdir). Unsupported operations fall back to the thread pool.

To enable, compile with --enable-io-uring (requires liburing):

phpize && ./configure --enable-io-uring && make && sudo make install

Event loop lag metrics

$server->stats() now exposes event loop lag metrics per worker:

  • event_loop_lag_ms - current event loop lag in milliseconds
  • event_loop_lag_max_ms - maximum event loop lag observed
  • event_loop_lag_avg_ms - average event loop lag

Available in worker processes, coroutine-enabled task workers, and reactor threads (process mode). Useful for detecting blocking operations that stall the event loop.

Coroutine-safe exit()

On PHP 8.4+, exit() calls inside coroutines are intercepted and throw openswoole_exit_exception instead of terminating the entire process.

HTTP parser migration to llhttp

The custom openswoole_http_parser has been replaced with llhttp for improved standards compliance and performance. This is an internal change and should not affect user-facing APIs.

Namespace normalization

Internal function and class naming has been normalized to use the openswoole_* prefix consistently.

Backward compatibility constant aliases

Backward compatibility constant aliases have been added to ease the transition.

Removed features

  • PHP < 8.0 compatibility code has been removed
  • PHP 8.2 support has been dropped

Install / Upgrade

# PECL
pecl install openswoole-26.11.0

# Core library
composer require openswoole/core:26.11.0

Or compile from source:

git clone https://github.com/openswoole/ext-openswoole.git
cd ext-openswoole
git checkout v26.11.0
phpize && ./configure --enable-openssl --enable-http2 --enable-mysqlnd --enable-sockets --enable-hook-curl --with-postgres --enable-cares
make && sudo make install
Last updated on November 18, 2026