Platform Notes
Behaviour of OpenSwoole 26.2, PHP 8.5 and the extensions Core builds on that shaped the implementation. Each item names the Core component that accounts for it. The integration suite covers these behaviours, so a regression in a newer runtime version shows up as a test failure.
Coroutines and timers
Coroutine::sleep()andCoroutine\System::sleep()declare anintparameter; fractional seconds truncate (0.5 → no wait). →Runtime\Coroutine\Sleep::for(float)uses a timer.Channel::pop()/push()timeouts below one millisecond round to zero and become indefinite waits. → pools checkisEmpty()/isFull()before non-blocking operations.- An uncaught exception in an OpenSwoole coroutine is fatal for the worker process.
→
Coroutines::spawn()contains failures and reports them. Timer::clear()/exists()arginfo declares no parameters although the id is required. →Runtime\Coroutine\Timerswraps them.- The fiber context backend (
use_fiber_context) makes coroutine creation orders of magnitude slower than the default backend. → not enabled.
Server lifecycle
- On SIGTERM, POOL mode keeps connections of suspended requests open until their handlers finish; SIMPLE mode exits the worker's event loop immediately and closes them. Reload (SIGUSR1) drains in both modes. → POOL mode is the default.
- A worker receives requests as soon as its
WorkerStartcallback suspends on I/O. → services are registered before any warm-up that yields; pools create connections lazily. WorkerStopruns outside a coroutine; channel and socket APIs fail there. → pools track live connections in arrays and close them synchronously.- Signal handlers cannot be installed in server workers (OpenSwoole owns them).
→
Runtime\Shutdown\SignalHandleris for standalone coroutine programs only. - Processes cannot be forked inside a coroutine. → the CPU pool uses
Server::addProcess(). - The io_uring reactor aborts on kernels < 5.1 instead of falling back.
→
RuntimeConfigrefusesreactor => io_uringthere; epoll is the default. - On kernels < 5.1 the io_uring file engine falls back to the thread pool but OpenSwoole may
log warnings for every AIO batch. → set
log_fileorlog_level.
HTTP transport
- Above
package_max_lengththe server answers413and closes the connection; oversized headers get400; a malformed request line closes the connection without a response. - After a client disconnect
Response::write()returnsfalsewhileisWritable()still reportstrue. →ResponseWritertracks write results (clientGone()). - Once
write()started chunked mode, the body passed toend()is discarded. →ResponseWriter::end()sends it as a final chunk. OpenSwoole\Http\Request::create()->parse()rejects lower-case methods.
Outbound HTTP
- The native curl hook can crash the process when libcurl resolves remote host names itself,
and does not reuse connections across
curl_exec()calls. →Coroutine\Http\Clienttransport (ADR-002). Coroutine\Http\Clientdoes not verify TLS peers unlessssl_verify_peeris set, and needsssl_host_namefor SNI. → always set by the transport.- The client does not follow redirects and buffers response bodies (
write_funcis not invoked for ordinary responses). → redirect policy and size limits are implemented in Core;download()streams to files. - DNS failures surface as error code 711 (or similar resolver errors) →
DnsException.
Database
- Only mysqlnd-based
pdo_mysqlis coroutine-compatible;pdo_pgsqlis not hooked. PDO::ATTR_TIMEOUTbounds connects but not reads under hooks. → server-side statement limits (max_statement_timeon MariaDB,max_execution_timeon MySQL).- One PDO object used by two coroutines at once fails either with a catchable error or with a fatal "Socket#N has already been bound to another coroutine". → ownership assertions.
- A coroutine cancelled during a query leaves the connection unusable ("server has gone away" on next use). → the pool discards connections after interrupted operations.
- PHP 8.5 deprecates
PDO::MYSQL_ATTR_INIT_COMMAND; with warnings promoted to exceptions this breaks connections. → session statements run withexec()after connecting.
Redis
- phpredis reports server error replies by returning
false(withgetLastError()), not by throwing. →RedisClientconverts them intoCommandException. OPT_PREFIXalso prefixes pub/sub channel names. →subscribe()strips it before invoking handlers.
Static analysis
OpenSwoole\Process::alarm()referencesITIMER_REAL, which some builds without pcntl constants do not define; PHPStan's reflection then fails. →tests/phpstan-bootstrap.phpdefines the POSIX values for analysis only.