What Threads Broke in Ten PHP Extensions

●7 ●38
calendar_today ago • schedule12 min read
— Originally published at ilia.ws

Four requests hit the same FrankenPHP server at once, and each one runs a single-threaded aggregate over the same DuckDB file:

$db = new PDO('duckdb:/data/shared.duckdb');
$db->exec('SET threads=1');
$t = hrtime(true);
$r = $db->query('SELECT sum(i % 7) FROM range(150000000) t(i)')->fetchColumn();
printf("%s %.2f s\n", $r, (hrtime(true)-$t)/1e9);

With pdo_duckdb 0.9.0, the October release, on PHP 8.5.13 ZTS:

449999994 6.36 s
449999994 2.13 s
449999994 2.52 s
449999994 6.36 s
wall: 9.19 s

With 0.10.0, released yesterday:

449999994 1.76 s
449999994 1.80 s
449999994 1.69 s
449999994 1.64 s
wall: 2.01 s

The timer includes the wait. On 0.9.0 the thread-safe build serialized every query on a shared database file, so two of the four requests spent most of their 6.36 seconds queued behind the others. Part of the gap is DuckDB itself: 0.10.0 bundles DuckDB 2.0.1, and one uncontended query took 2.32 s on 0.9.0 and 1.54 s on 0.10.0. The queueing is the rest. In 0.10.0 SELECT statements on one file run concurrently, while writes still queue so concurrent autocommit updates don't collide. A second run of each gave 9.40 s and 3.54 s of wall time.

That bug is typical of this round. Most PHP extensions are written and tested under php-fpm, where a process serves one request at a time and anything global to the process is, in practice, private to the request. FrankenPHP and other threaded SAPIs run many requests in one process, so every setlocale(), getenv(), static cache, and _exit() becomes shared with every other request in flight. Six of my ten extensions shipped fixes for exactly that on November 20 and 21, right after PHP 8.6.0 came out on the 19th. The same releases add PHP 8.6 support to all ten. Four of them, phpser, fastjson, mdparser, and pdo_duckdb, also carry the startup check I promised in the last roundup: a prebuilt binary now refuses to start on a PHP patch older than the one it was compiled against, instead of loading and crashing mid-request on a missing symbol. The first mdparser build with that check refused a PHP release it could have run on; more on that below.

Project Release Threading fix in this release
pdo_duckdb 0.10.0 Concurrent SELECT on a shared file; max_execution_time interrupts queries
php_excel 2.10.0 LibXL locale changes no longer reach other threads
phpser 0.11.0 session.auto_start crash on each new thread; stack-depth check
fastchart 1.9.0 Shutdown crash, putenv() race, vendored assert() aborts
statgrab 2.3.2 Hung mount blocking other threads; errors leaking across requests
php_clickhouse 0.14.0 Conversion state leaking into later requests
fastjson 0.11.0 None; memory_limit stop and SIMD UTF-8
mdparser 0.9.1 None; SIMD UTF-8 and the startup check
phonetic 0.5.0 None; encoder speedups
fast_uuid 0.10.0 None; ramsey/uuid 4.10 parity

Process-wide state is shared state

Under php-fpm, process-wide state can only leak from one request into the next one on the same worker. Under threads, it leaks sideways into requests running at the same moment. Each bug in this section is a global that was safe for one model and wrong for the other.

The worst was in php_excel. LibXL changes the C locale while it creates, loads, saves, or releases a workbook, and setlocale() applies to the whole process. On a thread-safe build, two concurrent saves could leave LC_NUMERIC set to C for every thread, and merely having a workbook open switched LC_CTYPE for every thread too. Requests that never touched a locale had it changed underneath them. 2.10.0 runs LibXL on a per-thread locale built from its own changes on top of C, and phpinfo() reports it as "LibXL locale isolation".

That fix changes behaviour. On thread-safe builds on Linux with glibc, LibXL no longer follows a locale your PHP code sets with setlocale(). If you relied on that, call ExcelBook::setLocale() instead. Non-thread-safe builds still follow setlocale().

The others are smaller, and each has the same shape:

  • statgrab 2.3.2: an sg_fs_stats() call stalled on a hung mount blocked other threads' sg_fs_stats() and sg_valid_filesystems() calls on glibc. And sg_error_details() could report an error from an earlier request on the same thread, including an earlier HTTP request in FrankenPHP worker mode.
  • php_clickhouse 0.14.0: a conversion that a fatal error left unfinished kept its NULL and nesting-depth state, and the state is per thread. Under a threaded SAPI a later request could have NULL accepted for a non-Nullable external column, or nested results fail with "nested-type depth exceeds limit".
  • fastchart 1.9.0: NetworkChart read FASTCHART_NETWORK_SCALAR without PHP's environment lock, so a putenv() in another thread could race it.
  • pdo_duckdb 0.10.0: opening or closing a connection in one thread could wait on a slow query against a different database file that another thread was closing.

Thread lifecycle is where the crashes were

A php-fpm worker starts its module once and serves requests until it exits. A threaded server starts threads, retires them, and sometimes unloads the module while some of them are still around, and each of those transitions had a crash somewhere in the fleet.

phpser 0.11.0 fixes the one most likely to hit a real deployment. With session.auto_start=1 and session.serialize_handler=phpser on a ZTS build, the first request on each new thread crashed, because ext/session decoded the stored session before phpser had set up that thread. FrankenPHP and the embed SAPI both hit it.

fastchart 1.9.0 had two. Embed-SAPI hosts can let worker threads exit without calling ts_free_thread(), and PHP then runs the extension's globals destructor for each of those threads from the main thread at shutdown. The destructor released the calling thread's FreeType state and caches instead of the ones it was handed. The other was an assert() in vendored plutovg and qrcodegen code, which fastchart compiled without -DNDEBUG. Under php-fpm a failed assertion would have killed one worker. Under a threaded SAPI, abort() ended every request the process was serving. Both libraries are now built the way their own release builds are.

statgrab 2.3.2 stops a thread that used it from crashing on exit when the host unloaded the extension first. phpser 0.11.0 wipes a thread's cached signing keys and derived subkeys when ts_free_thread() releases it; before, only the thread running module shutdown wiped its copy. phpser 0.10.2 also picked up a fix from Michael Grunder: building phpser statically into a ZTS PHP failed to link with a duplicate _tsrm_ls_cache symbol.

Thread stacks are smaller than process stacks, too. musl's default is 128 KiB. On PHP 8.3 and later, phpser 0.11.0 throws the engine's "Maximum call stack size" Error when encoding runs low on C stack, and rejects the payload when decoding does, instead of crashing. That covers deep nesting and __serialize() methods that call phpser_serialize() recursively.

pdo_duckdb 0.10.0 also makes max_execution_time stop a running DuckDB query: the driver interrupts the query when the limit expires. That works on Linux and FreeBSD thread-safe builds and on non-thread-safe POSIX builds. Thread-safe builds on macOS and all Windows builds still run the query to completion first.

One memory_limit overrun can take the whole server down

The last post covered the October change to memory_limit: on PHP 8.2.35, 8.3.36, 8.4.27, 8.5.12, and now 8.6.0, the engine records the error and raises it at the next safe point instead of bailing out at once. A C loop that never reaches a safe point keeps allocating until the hard limit, by default twice memory_limit, and the engine calls _exit(). Under php-fpm that costs one worker. Under FrankenPHP, exit status 137 ends the whole server and every request in it.

This round extends the stop to the extensions that didn't have it yet:

  • fastchart 1.9.0: SVG builds and the PNG, JPEG, and WebP encoders kept appending output past the limit, and a raster frame larger than twice memory_limit was allocated in one step. An 8192x8192 renderPng() at the default 128M could reach the hard limit on its own. A raster renderToFile() that hit the limit also left its temporary file behind.
  • fastjson 0.11.0: decoding, encoding, the pointer functions, and fastjson_merge_patch() stop at a pending error. The changelog states the limit of that fix: one allocation larger than the room left below the hard limit, such as encoding one very large string, still ends the process.
  • php_clickhouse 0.14.0: select(), selectStatement(), and selectWithExternalData() stop converting rows once the result exceeds memory_limit, and no method throws a ClickHouseException while the error is pending, so no catch block runs before the fatal.
  • statgrab 2.3.2: on PHP 8.5.12 and later, and 8.6, a stat call whose result outgrows memory_limit ends with the usual fatal error.
  • phpser 0.11.0: the remaining loops, objects with many properties, long __sleep() lists, wide row schemas, and long allowed_classes lists, now stop as well.

Whether you get the stop depends on how the binary was built, because each of these checks is compiled in only against headers that define ZEND_HAS_OOM. Source builds on a patched PHP always have it. The prebuilt binaries fall into two groups:

Prebuilt Linux and macOS binaries for 8.4 and 8.5 Built against Has the stop Runs on
phpser, fastjson, mdparser, pdo_duckdb 8.4.27 and 8.5.12 Yes 8.4.27+ and 8.5.12+ only
fastchart, php_clickhouse 8.4.1 and 8.5.0 No Any 8.4 or 8.5 patch

8.6 binaries are built against 8.6.0, which defines it. statgrab ships no binaries, so it always builds from source.

The version check shipped, and misfired once

In October I wrote that the next releases of pdo_duckdb, phpser, and mdparser would refuse to start on a PHP patch older than the one they were compiled against, instead of loading and dying later with undefined symbol: smart_str_ferealloc. phpser 0.10.2 shipped it on October 30, and fastjson 0.11.0, mdparser 0.9.0, and pdo_duckdb 0.10.0 followed this week. With the check in place, phpser, fastjson, and mdparser moved their prebuilts back to the patched headers and regained the memory_limit stop; pdo_duckdb had kept its prebuilts there since 0.9.0.

mdparser 0.9.0 then built its prebuilts against PHP 8.4.28 and 8.5.13. Those patches came out on November 19, the same day as 8.6.0, and the release workflow picked up the newest patch of each minor as designed. This is the 0.9.0 binary on the php:8.4.27-cli image:

Warning: mdparser was built for PHP 8.4.28 and cannot run on PHP 8.4.27; install a build for this PHP version or build from source in Unknown on line 0

Fatal error: Unable to start mdparser module in Unknown on line 0

8.4.27 exports every symbol that binary imports. The check doesn't ask about symbols. It compares php_version_id() with PHP_VERSION_ID, so a build against the newest patch locks out every server that hasn't upgraded since the day before. 0.9.1, five hours later, builds against 8.4.27 and 8.5.12 again. On the same images it runs on 8.4.27 and refuses 8.4.26 with the same warning, which is the behaviour I wanted in the first place. The floor has to be the oldest patch that exports what the binary needs, and the build has to be pinned to it rather than to whatever is newest.

phpser had a different mistake. The check is there because Linux and macOS resolve a missing symbol lazily, at the first call, mid-request. Windows resolves imports when the DLL loads, so the check adds nothing there, and phpser 0.10.2 and 0.10.3 applied it on Windows anyway. Those DLLs refuse to start on any earlier patch of their minor. 0.11.0 applies the check only on Linux and macOS, and fastjson skips it on Windows from the start. pdo_duckdb's Windows binaries are the exception in the other direction: they require 8.2.36+, 8.3.37+, 8.4.28+, 8.5.13+, or 8.6.0+.

PIE still selects the prebuilt binary on an older patch. On 8.4.26 you get the startup warning instead of a crash, but you still have to upgrade PHP or build from source.

PHP 8.6 binaries

PHP 8.6.0 shipped on November 19. Every extension has 8.6 support in this round, and nine of them attach 8.6 binaries to the release:

Project Linux glibc x86_64 and arm64 macOS arm64 Windows
fast_uuid 0.10.0 Yes Yes x64 and x86, TS and NTS
fastchart 1.9.0 Yes Yes x64 and x86, TS and NTS
fastjson 0.11.0 Yes Yes x64, TS and NTS
mdparser 0.9.1 Yes Source build via PIE x64 and x86, TS and NTS
pdo_duckdb 0.10.0 Yes, NTS and ZTS, plus musl Yes, NTS and ZTS x64, TS and NTS
phonetic 0.5.0 Yes Yes x64 and x86, TS and NTS
php_clickhouse 0.14.0 Yes Source build via PIE x64 and x86, TS and NTS
php_excel 2.10.0 Source build Source build x64 and x86, TS and NTS
phpser 0.11.0 Yes Yes x64 and x86, TS and NTS
statgrab 2.3.2 Source build Source build No binaries

pdo_duckdb's 8.6 builds replace the release-candidate builds it shipped before. fast_uuid and mdparser also run an advisory CI job against php-src master (8.7-dev), which opens an issue when the weekly run fails.

Performance, with the hardware attached

fastjson and mdparser now validate UTF-8 16 and 64 bytes at a time respectively, with SSSE3 on x86-64 and NEON on ARM64. I measured the released Linux x86_64 binaries against their previous releases on my i9-13950HX, in the php:8.4.27-cli image, best of seven, two runs each:

Workload Before After
mdparser toHtml(), 3.5 MB of Russian-text Markdown 0.8.2: 32.1-32.6 ms 0.9.1: 16.1-16.8 ms
mdparser toHtml(), 3.0 MB of Chinese-text Markdown 0.8.2: 22.2-28.9 ms 0.9.1: 13.4-16.2 ms
mdparser toHtml(), 2.1 MB of ASCII Markdown 0.8.2: 10.8-12.0 ms 0.9.1: 9.3-9.5 ms
fastjson_validate(), 8.8 MB of Russian-text JSON 0.10.2: 10.3-10.7 ms 0.11.0: 3.4-4.5 ms
fastjson_decode(), same document 0.10.2: 30.6 ms 0.11.0: 20.3-23.1 ms

The laptop is noisy, so read those as ranges. The fastjson changelog states the trade-off: ASCII-only encoding is about 1.5% slower.

From the changelogs, with the conditions they state:

  • phpser 0.11.0 writes a top-level scalar or string straight into the result. On Linux x86-64 with GCC 14, the bench.php --extended string_15 and int_single shapes take 52-56% less encode time, and a 1 MiB string 91% less.
  • phonetic 0.5.0 reworks the BMPM, Daitch-Mokotoff, and Double Metaphone internals, and the changelog measures each change on its own; the first BMPM change takes 10-23% off bmpm() and bmpm_match() on a list of Latin-script surnames (Linux x86-64; GCC 12 and 14, Clang 18). Corpus-digest tests pin the encodings, so none of the output changed. BMPM is still the slowest encoder in the extension by a wide margin. It is there for recall.
  • fastchart 1.9.0: WordCloud SVG renders of 60-256 words take 36-90% less time (Linux x86-64; GCC 12.2 and 14.2, Clang 18.1), with output unchanged.

Three fixes from Nicolas Grekas

phpser 0.10.2 carries three fixes Nicolas Grekas wrote. A positional object of a class denied by allowed_classes lowercased and hashed its whole class name again for every object, so a 1 MB payload that repeated a long class name could take a minute of CPU. A __serialize hook that deleted a later row of a top-level ArrayObject or ArrayIterator storage array made the encoder read freed heap. And phpser_serialize_signed() and phpser_unserialize_signed() now mark $key with #[\SensitiveParameter], so exception traces no longer contain the signing key.

Changes to read before you upgrade

  • Prebuilt Linux and macOS binaries of phpser, fastjson, mdparser, and pdo_duckdb require PHP 8.4.27+ or 8.5.12+, and pdo_duckdb's also accept 8.2.35+ and 8.3.36+. On an older patch they refuse to start.
  • php_excel 2.10.0, thread-safe builds on Linux with glibc: LibXL ignores setlocale(); use ExcelBook::setLocale(). Unsupported data-validation, filter, and conditional-formatting types and operators now warn and return false instead of writing empty XLSX attributes.
  • phpser 0.11.0: an allowed_classes option that is neither an array nor a bool throws TypeError, not ValueError, matching native unserialize(). On PHP 8.4 and later, invalid class names in the list throw ValueError before any decode hooks run.
  • fastjson 0.11.0: a malformed escape such as "\x" reports JSON_ERROR_SYNTAX, as json_decode() does, instead of JSON_ERROR_UTF8. A $depth outside the int range throws ValueError.
  • fast_uuid 0.9.0: the compat validators accept exactly what ramsey/uuid 4.10's accept, so GenericValidator no longer checks version or variant, and a prefix inside braces is rejected. getDateTime() on v1, v2, and v6 UUIDs rounds to the nearest microsecond instead of truncating.
  • pdo_duckdb 0.10.0 bundles DuckDB 2.0.1. Fetched nested values now quote a scalar UNION member inside a LIST, ARRAY, STRUCT, or MAP, matching CAST(... AS VARCHAR) on 2.0.1.

Test under the SAPI you deploy on

Most of the bugs in the first two sections need two requests in one process to show up, and a test suite that runs one request per process never produces that. None of them is exotic. A locale switch, an environment read, a debug assertion, and a lock held per file instead of per write are all ordinary C, and all safe until a second request runs beside them. If you run FrankenPHP or another threaded SAPI, upgrade php_excel and pdo_duckdb first, and test your own extensions under the threads you deploy, not only under php-fpm.

Want more #opensource & #performance deep dives?

Join 5,976+ developers sharing real benchmarks, code breakdowns, and projects. Free forever.

More Posts

AAIF Hits 10 Projects. Its CTO on What to Adopt Now and the Security Gaps Left Open

Tom Smithverified - Oct 23

I Wrote a Script to Fix Audible's Unreadable PDF Filenames

snapsynapseverified - Apr 20

The Sovereign Vault — A Comprehensive Guide to Protocol-Driven AI

Ken W. Algerverified - Jun 4

Your AI Agent Skills Have a Version Control Problem

snapsynapseverified - Apr 22

Core Web Vitals Benchmarks for Shopify Stores (2026 Data)

ApogeeWatcherverified - Sep 16
chevron_left
692 Points • 45 Badges
22Posts
6Comments
6Connections

Related Jobs

View all jobs →

Commenters (This Week)

2 comments
1 comment

Contribute meaningful comments to climb the leaderboard and earn badges!