DEV Community: Ilia Alshanetsky

fastjson 0.3.0: A Faster Drop-In ext/json for PHP, Backed by yyjson

Ilia Alshanetsky — Wed, 20 May 2026 11:35:45 +0000

// Before
$payload = json_encode($response);
$data    = json_decode($input, true);
$ok      = json_validate($input);

// After
$payload = fastjson_encode($response);
$data    = fastjson_decode($input, true);
$ok      = fastjson_validate($input);

That's the migration. Search-and-replace json_* for fastjson_*. JSON flags, error constants, and last-error semantics carry across byte-for-byte. The two extensions sit next to each other in the same process; adoption is per call site, not per repo.

On the simdjson_php canonical 14.8 MB corpus, that swap buys 6.06× encode throughput, 2.66× decode, and 5.10× validate against ext/json on the same PHP 8.6.0-dev build. The repo is at github.com/iliaal/fastjson. 0.3.0 shipped yesterday.

Why drop in faster JSON for PHP

ext/json is fine. It's correct, well-maintained, and tracks the spec. On low-traffic endpoints it isn't on anyone's profiler. The cost shows up at scale: any application that calls json_encode and json_decode on every request path eventually finds JSON serialization sitting at the top of a flame graph. API gateways feel it first, then log processors and microservice fan-out paths.

Before fastjson the practical options were two:

Stay on ext/json. Eat the CPU cost.
Reach for simdjson_php. It's fast but decode-only and not API-compatible; every call site has to be rewritten around its result shape.

fastjson is option three. It's a native PHP extension that wraps yyjson 0.12.0 (MIT, ~6K LOC of focused C) behind a namespaced API that mirrors ext/json's contract. PHP 8.3 minimum; 8.4 and 8.5 supported; coexists with ext/json.

What "drop-in" actually means here

The risk with any "drop-in" claim is that it covers 90% of cases and silently changes behavior on the 10% that matter. So this section is what fastjson does and what it doesn't:

Function signatures track ext/json. fastjson_encode($value, int $flags = 0, int $depth = 512). Same positional shape. Same defaults. Same return values on success, false on failure.
JSON_* flags match byte-for-byte. JSON_UNESCAPED_SLASHES, JSON_UNESCAPED_UNICODE, JSON_PRETTY_PRINT, the JSON_HEX_* family, JSON_THROW_ON_ERROR, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE. The integer constants are intentionally identical so user code can pass the same flag value into either function.
JSON_ERROR_* codes match byte-for-byte, messages don't. fastjson_last_error() returns the same JSON_ERROR_* int as json_last_error() for the same failure class, so code branching on error codes works without modification. fastjson_last_error_msg() returns yyjson's parser message (e.g., "unexpected character"), not ext/json's. Application code that pattern-matches on the message string needs updating; code that branches on the code does not.
Coexistence, not replacement. Both extensions load. Migrate the call sites where JSON is on the hot path; leave the rest on ext/json.
53 phpt tests rewritten from php-src/ext/json/tests/*.phpt run alongside fastjson's own suite. The rest of the upstream suite is categorized in tests/upstream-json/.skiplist with the reason each test was deferred (most are tests of ext/json internals that don't translate, a few hit known divergences).
Documented divergences. Large/scientific doubles emit 100000000000000000.0 where ext/json emits 1.0e+17 in some ranges. U+2028 / U+2029 line separators emit as ordinary code points; ext/json always escapes them for JSONP safety. Both divergences are in the skiplist with rationale.

The numbers

Full simdjson_php canonical corpus: 14.8 MB across 15 files, the same set the simdjson PHP binding has been benchmarked against for years. Hardware: i9-13950HX. PHP 8.6.0-dev, release build (-O2). fastjson built -O2 against the same PHP. yyjson 0.12.0 with three local patches. Numbers in throughput, MB/sec:

Operation	fastjson	ext/json	Speedup
Decode (stdClass)	602 MB/s	227 MB/s	2.66×
Decode (assoc array)	628 MB/s	237 MB/s	2.65×
Encode	1,092 MB/s	180 MB/s	6.06×
Validate	1,352 MB/s	265 MB/s	5.10×

Visual side-by-side, including ext/json with Nora Dossche's open SIMD encode work (php-src#17734) and simdjson_php on the same PHP 8.6.0-dev build, lives at https://iliaal.github.io/fastjson/baseline.html. Reproduce locally with bench/run.php against any PHP install.

The encode speedup is the largest gap because the PHP-native encoder has the most room to give back. ndossche's php-src#17734 patch closes a meaningful chunk of that gap inside ext/json itself using SIMD on string encoding. fastjson and that PR attack the same problem from different angles, and an application can benefit from both once #17734 lands upstream (fastjson re-baselines automatically; the visual page already shows both).

How the encoder gets to 6×

The encoder is one-stage. A zval walks straight into a smart_str buffer via yyjson's writer primitives. There's no intermediate DOM, no two-pass build-then-serialize, no temporary string allocations for the common-case scalars. Each PHP value type maps to one or two yyjson calls; arrays and objects walk recursively into the same path.

A few less-obvious pieces:

Custom allocator wired through Zend. yyjson's allocator hooks route every alloc/realloc/free through PHP's emalloc family. JSON workloads count against memory_limit and against per-request memory accounting; oversized inputs bail out the same way any other PHP allocation does.
Direct smart_str integration. No RETURN_STRING(estrdup(buf)) after a separate allocation. The yyjson writer writes into the smart_str.s backing store, which becomes the return zend_string directly. One allocation per encode call in the common case.
HEX_* flag scan-first. The flags JSON_HEX_TAG/HEX_AMP/HEX_APOS/HEX_QUOT rewrite specific characters into hex escapes. fastjson scans the string once for any candidate character; if none are present, the rewrite path is skipped entirely and the string is encoded directly. Defensive callers that pass HEX_* flags as a precaution on payloads that don't actually contain the substituted characters don't pay the rewrite cost.
Integer-valued-double shortcut. When a double round-trips losslessly through int64, fastjson emits it as an integer without going through php_gcvt or yyjson's REAL writer. A cheap range check fires before floor(), so number-heavy arrays of non-integer doubles don't pay libm per element.

The decode path's gain has different sources: yyjson itself, which parses with less branching and tighter memory locality than ext/json's parser, and a local yyjson patch (YYJSON_READ_VALIDATE_ONLY) that turns the read path into a fast validate-only mode without materializing values.

The memory tradeoff

Worth surfacing before anyone hits it in production. Decode and validate hold the yyjson document object in memory alongside the PHP-side result, because yyjson's value graph is built first, then traversed to produce zvals. Peak heap on decode is roughly 1.7× what ext/json peaks at on the same input. Encode is one-stage and peaks at ~1.06× of ext/json.

Validate is the loudest: peak heap is ~101× ext/json's streaming validator (which sits at a constant ~80 bytes since it doesn't materialize anything). The headline number sounds extreme, but the absolute footprint is bounded by yyjson's read path, and it's already 2.7× lower than yyjson's stock read path thanks to a vendored validate-only patch (YYJSON_READ_VALIDATE_ONLY) that skips the value-graph build.

For most callers, the speedup wins. If the application is validate-heavy on giant inputs under tight memory_limit, the memory profile is a real consideration. The right move there is to leave validate-on-huge-inputs on ext/json and migrate the encode and decode paths. That's exactly what coexistence buys.

Compat harness

53 rewritten phpt tests from php-src/ext/json/tests/*.phpt run alongside fastjson's native suite. They cover the common decode/encode/validate paths, the flag combinations, and the documented error conditions.

The two remaining intentional divergences:

Large/scientific doubles. Outside the integer-valued-double shortcut range, fastjson emits yyjson's real-number format. ext/json uses php_gcvt and switches to scientific notation earlier. The disagreement window narrowed in 0.3.0; what's left is the genuinely-fractional case where yyjson and php_gcvt produce different decimal representations of the same IEEE 754 double.
U+2028 / U+2029 line separators. ext/json always escapes these for JSONP safety. yyjson treats them as ordinary code points. fastjson follows yyjson's behavior. If JSONP is in the deployment path, set JSON_UNESCAPED_UNICODE off in ext/json and stay on ext/json for that endpoint, or wrap fastjson output through a JSONP-safe post-step.

Upstream collaboration with yyjson

fastjson vendors yyjson 0.12.0 with three local patches. Full details are in vendor/yyjson/PATCHES.md; the short version of each, and what happened when each was proposed upstream:

Lowercase hex digits in \uXXXX escape table. yyjson emits uppercase; ext/json emits lowercase. RFC 8259 §7 allows either, but byte-parity with ext/json is the project's compat goal. Proposed as yyjson#264 (YYJSON_WRITE_LOWERCASE_HEX flag) and accepted upstream on 2026-05-11. fastjson will drop this patch once the vendored sources advance past yyjson 0.12.0.
YYJSON_READ_VALIDATE_ONLY, no-tree validate mode. Forks yyjson's parser entry point to skip the value-graph build entirely; peak memory drops 2.7× on the validate corpus. Not yet proposed upstream; the API surface needs a round of review before it's ready to submit.
Public yyjson_write_string_to_buf() wrapper. Exposes yyjson's internal direct-write primitive so fastjson's one-stage encoder can compose at the buffer level. Proposed as yyjson#266 and closed upstream; the maintainer preferred to keep that surface private. The wrapper stays vendored locally; fastjson lives with it indefinitely.

Install

pie install iliaal/fastjson

Or build from source:

phpize
./configure
make -j
make test
sudo make install

PHP 8.3 minimum. No external library dependencies; yyjson is vendored in src/yyjson/.

The four-character migration

fastjson stays useful as long as yyjson's design choices (one-stage encoder, validate-only fast path, allocator hooks) beat what fits into ext/json's compatibility envelope. For the call sites where JSON serialization shows up on a flame graph, the migration is four characters; the rest of the codebase doesn't have to care.

Repo: https://github.com/iliaal/fastjson. Benchmark methodology and reproduction: bench/run.php. Visual baseline: https://iliaal.github.io/fastjson/baseline.html.

fastchart 0.2.0: Native PHP Charts, Barcodes, and QR Codes in One Extension

Ilia Alshanetsky — Tue, 12 May 2026 13:50:03 +0000

(new FastChart\StockChart())
    ->setSize(1200, 600)
    ->setTitle('AAPL last 90 days')
    ->setTheme(FastChart\Chart::THEME_DARK)
    ->setOhlcv($ohlcvRows)
    ->setMovingAverages([20, 50, 200])
    ->setVolumePane(true)
    ->setCandleStyle(FastChart\Chart::STYLE_HOLLOW)
    ->renderToFile('/tmp/aapl.png');

That's a server-side OHLCV candlestick chart with three moving averages, a volume pane, and a hollow candle style. Roughly 68 ms on a single core at 1920×1080. No microservice, no Node sidecar, no JavaScript runtime. PHP, gd, fastchart.

fastchart 0.2.0 shipped two days ago. 19 chart types behind a fluent OO API, plus a Symbol family (Code 128 barcodes and QR codes) that landed in this release. The repo is at github.com/iliaal/fastchart.

Why charts in PHP again

Twenty years ago, Rasmus and I shipped the initial release of PECL/GDChart in January 2006. It wrapped Bruce Verderaime's gdchart C library from users.fred.net/brv/chart/. The PECL page is still up at https://pecl.php.net/package/GDChart.

Both projects died. Verderaime's gdchart library hasn't moved since the mid-2000s; the homepage at users.fred.net/brv/chart/ has been a tombstone for almost as long. The PECL extension followed. One release, then nothing.

The PHP charting ecosystem since then has been thin. JpGraph kept moving but active development went to the commercial fork; the OSS branch is calcifying. pChart is unmaintained. Many PHP teams that need server-side charts in 2026 either reach for a Node or Python microservice (Chart.js via Puppeteer, matplotlib via subprocess) or accept that "server-side rendering" means "render in the browser and screenshot it." Neither is good.

Between PECL/GDChart and now, I've kept needing charts and graphs in PHP. Mostly charts, occasionally barcodes and QR codes. Each new project I'd reach for the easy options first: command-line tools wrapped through shell_exec, pure-PHP libraries when they were fast enough, more recently chart.js renders shipped through a Puppeteer or headless-Chrome wrapper. Those work until they don't. When scale showed up the wrapper started dominating request latency, and I'd write a little PHP extension that handled the specific case causing pain.

Roughly six of those extensions accumulated over the years. Each did one thing. One generated QR codes for serial numbers on physical labels. One drew two chart types for an internal reporting dashboard. One was just OHLC candlesticks with moving averages. None of them shipped. They lived in private repos, solved the immediate problem, and never got cleaned up enough to release.

fastchart is the attempt to close that gap publicly. One extension, the breadth of shapes I've kept needing, a fluent OO API, BSD-licensed. StockChart got the deepest treatment in this release (seven candle styles, the full indicator stack) because the most recent of the six private extensions was the trading-chart one and it carried over almost verbatim. The other eighteen chart types and the Symbol family came from cleaning up and merging the rest.

What's in 0.2.0

Nineteen chart classes plus a two-class Symbol family for barcodes and QR codes. Five output formats. Two render paths. The full surface is 105 public methods covered by 97 tests. PHP 8.3+ minimum, NTS or ZTS.

The chart classes split into four shapes:

Cartesian. Line, Area, Bar (vertical, horizontal, stacked, grouped, floating, layered), Scatter, Bubble.
Financial. A deep StockChart class: seven candle styles (CANDLE, BAR, DIAMOND, I_CAP, HOLLOW, VOLUME, VECTOR), SMA/EMA/WMA overlays, a volume pane, and indicator panes (RSI, MACD, Bollinger Bands, Parabolic SAR, Stochastic, OBV).
Non-Cartesian. Radar, Polar, Surface, Contour.
Specialised. Pie (with donut hole and leader lines), Gauge, LinearMeter, Gantt (with dependencies and milestones), BoxPlot, Treemap, Funnel, Waterfall, Heatmap.

The Symbol family added in 0.2.0:

Code 128. ISO/IEC 15417. Auto-switches between A/B/C subsets to minimize encoded length. Mod-103 checksum appended automatically. Optional human-readable payload rendered below the bars.
QR Code. ISO/IEC 18004. Four error-correction levels (ECC_L/M/Q/H), versions 1 through 40. Encoder is the vendored nayuki/QR-Code-generator C library under MIT.

Output formats are the standard gd set plus the modern ones: PNG, JPEG, WebP, AVIF, GIF.

Why barcodes and QR codes in a chart library

Because they all render to a gd canvas, they all serve the same use case (server-side image generation in PHP), and they share the same painful problem: the existing PHP-native options are mostly dead or third-party packages with their own dependency stacks.

The unifying thread is gd, not "chart." If you're rendering a dashboard tile, a sales report PDF, an invoice with a scannable serial number, or a shipping label with a barcode, you're producing an image on the server. PHP has had ext/gd since 4.0.0. fastchart treats ext/gd as the substrate and adds higher-level shapes on top. The Symbol classes don't claim to be charts; they live in their own family parallel to Chart, with shared base setters and the same render-format set.

The public options before fastchart were mostly pure-PHP libraries shipping their own glyph tables and rasterizers, or wrappers around command-line tools like qrencode. Both work. Both add a dependency surface that a pie install doesn't cover. fastchart pulls QR and Code 128 into the same .so as the charts. One install, one dependency (gd), one fluent API.

The compose path

Charts let you hand fastchart a \GdImage canvas you own. It draws into your canvas and returns the same canvas back. Symbols don't accept a caller-owned canvas (a barcode's quiet zone makes compositing inside an existing image ambiguous); they render fresh and you imagecreatefromstring() to composite afterwards.

The composability is the differentiator from JpGraph, pChart, and most JS-bridged solutions. They own the canvas. You get a finished PNG file back and composite at the file or page level, never at the pixel level. fastchart's two-path design covers both:

// Path 1: "give me a file."
(new FastChart\LineChart(800, 600))
    ->setSeries([['data' => $values]])
    ->renderToFile('/tmp/line.png');

// Path 2: "draw onto my canvas." Two charts side by side on the same image.
$canvas = imagecreatetruecolor(1600, 900);

(new FastChart\LineChart(1600, 900))
    ->setTitle('Daily active users')
    ->setSeries([['data' => $values]])
    ->setPlotRect(80, 60, 720, 820)
    ->draw($canvas);

(new FastChart\BarChart(1600, 900))
    ->setTitle('Quarterly revenue')
    ->setSeries([['data' => $bars]])
    ->setPlotRect(880, 60, 1520, 820)
    ->draw($canvas);

// Stamp something gd-native on top.
$font = '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf';
imagettftext($canvas, 24, 0, 20, 40, $white, $font, 'Dashboard');

imagepng($canvas, '/tmp/dashboard.png');

A four-tile dashboard, a chart embedded in a PDF page, a chart and its legend baked together on a sprite, same primitives, no separate render passes, no temp files.

Performance

Every chart type renders under 100 ms at 1920×1080 on a single core. The lighter types break 100 renders per second per core at dashboard-tile size (640×480). Numbers from my workstation (Intel i9-13950HX, PHP 8.4 NTS), default font and DPI.

Chart	640×480 ms	1920×1080 ms	1080p ops/sec
AreaChart	24	76	13
BarChart	39	84	12
BoxPlot	16	60	17
BubbleChart	13	62	16
ContourChart	9	52	19
Funnel	14	52	19
GanttChart	18	61	16
GaugeChart	10	60	17
Heatmap	9	56	18
LineChart	21	66	15
LinearMeter	9	50	20
PieChart	13	59	17
PolarChart	10	53	19
RadarChart	15	61	16
ScatterChart	17	60	17
StockChart	21	68	15
SurfaceChart	8	50	20
Treemap	18	60	17
Waterfall	18	61	16

These are not "we render faster than Chart.js running in Puppeteer" numbers. Headless-browser rendering is slow for completely different reasons (process startup, JS runtime, layout, paint). The honest framing is that fastchart removes the JS-render path entirely from server-side image generation. The benchmark is a sanity check that the C path is fast enough to stop reaching for a sidecar, not a marketing claim.

Bench source is at docs/bench/bench.php. Reproduce locally with php -d extension=gd -d extension=./modules/fastchart.so docs/bench/bench.php.

Install

pie install iliaal/fastchart

Or build from source against the PHP install you want to extend:

phpize
./configure --enable-fastchart
make -j
make test
sudo make install

PHP 8.3 or newer, plus ext/gd. fastchart declares ZEND_MOD_REQUIRED("gd") so the engine orders MINIT correctly regardless of php.ini / conf.d / -d extension= load order. (Earlier 0.1.0 didn't, and docker-php-ext-enable's alphabetical conf.d ordering caused fastchart to load before gd. That was the only thing 0.1.1 fixed.)

Twenty years later

The 2006 ext-gdchart was a hundred lines of glue around roughly 1,000 lines of upstream library. Single chart family, single output format, a tiny config surface. It worked. It died the moment its upstream did.

The bet with fastchart is the opposite: own enough of the substrate that the project's lifespan isn't bound to anything external besides gd, which has been in PHP since 4.0.0. Nineteen chart types, two symbol types, the whole stack lives in this repo. No third-party chart library to outlast, no microservice to keep alive, no JS toolchain to drag along.

Twenty years between PHP charting extensions is long enough.

mdparser: a native CommonMark + GFM parser for PHP

Ilia Alshanetsky — Wed, 06 May 2026 14:33:28 +0000

Several of my projects do heavy markdown parsing. Comment rendering, documentation pipelines, content management. The volume keeps growing, and I've been hitting the point where pure-PHP parsers (Parsedown, league/commonmark, cebe/markdown, michelf) just can't keep up. They're solid libraries, but parsing thousands of documents per request or chewing through 200 KB files in interpreted PHP is slow no matter how well the code is written.

I wanted something 10x+ faster that could serve as a drop-in replacement for the common cases. The result is mdparser, a native C extension that wraps cmark-gfm (GitHub's CommonMark parser) and exposes it through a clean PHP 8.3+ OO API. I'm releasing it today.

How it works

mdparser vendors a copy of cmark-gfm 0.29.0.gfm.13 directly into the extension's shared object. No external library to link against, no cmake, no runtime dependencies. The entire cmark-gfm codebase compiles alongside the PHP wrapper into a single .so (or .dll on Windows). Four cherry-picked commits from cmark upstream close the 0.29-to-0.31 spec gap, giving full CommonMark 0.31 conformance: 652 out of 652 spec examples pass.

The PHP API is intentionally small. Two classes, one exception:

use MdParser\Parser;
use MdParser\Options;

// Defaults: safe mode on, GFM extensions on.
$parser = new Parser();
echo $parser->toHtml('# Hello');

// Or the static shorthand:
echo Parser::html('# Hello');

// Custom options via named arguments:
$parser = new Parser(new Options(
 smart: true,
 footnotes: true,
 sourcepos: true,
));

// Three output formats:
$html = $parser->toHtml($markdown);
$xml = $parser->toXml($markdown);
$ast = $parser->toAst($markdown); // nested PHP arrays

Options is final readonly with 17 boolean fields. The Parser constructor translates those bools into cmark's internal bitmask once, so every subsequent parse call is pure cmark work with zero per-call overhead. Static factory presets (Options::strict(), Options::github(), Options::permissive()) cover common deployment patterns.

If you're migrating from Parsedown's line() or cebe/markdown's parseParagraph(), there's toInlineHtml(): inline-only HTML without the wrapping <p> tags. Useful for chat messages, table cells, and short user-facing strings.

Performance

This was the primary motivation. Measured on PHP 8.4 with each parser in its default configuration:

Parser	Small (200 B)	Medium (1.8 KB)	Large (200 KB)
mdparser	30,447 ops/s	5,697 ops/s	105 ops/s
Parsedown	1,651 ops/s (18x slower)	325 ops/s (17x)	6 ops/s (17x)
cebe/markdown (GFM)	1,350 ops/s (22x)	374 ops/s (15x)	6 ops/s (16x)
michelf (Extra)	1,006 ops/s (30x)	209 ops/s (27x)	5 ops/s (19x)

15-30x faster, from 200-byte chat messages to 200 KB documents. Your absolute numbers will differ by hardware, but the ratios hold. mdparser processes roughly 100 full CommonMark-spec-sized documents per second on a single core. The pure-PHP parsers manage 5-6.

The benchmark uses hrtime(true) around each parse call, 200 iterations with warm-up, trimmed mean to filter GC pauses. Reproducible scripts are in the bench/ directory.

Feature comparison

mdparser covers CommonMark core plus all five GFM extensions. Here's how it stacks up against the pure-PHP alternatives:

Feature	mdparser	Parsedown	league/cm	cebe GFM	michelf Extra
CommonMark core	full	partial	full	partial	partial
GFM tables	yes	yes	via ext	yes	via Extra
Strikethrough	yes	yes	via ext	yes	no
Task lists	yes	no	via ext	no	no
Autolinks	yes	yes	via ext	yes	no
Tag filter	yes	yes	via ext	partial	no
Smart punctuation	yes	no	via ext	no	no
Footnotes	yes	Extra	via ext	no	yes
Sourcepos	yes	no	yes	no	no
XML output	yes	no	no	no	no
AST output	yes (arrays)	no	yes (objects)	no	no

What mdparser doesn't do

mdparser is scoped to what cmark-gfm supports: CommonMark core plus five GFM extensions. It doesn't cover definition lists, abbreviations, attribute syntax, heading permalinks, table of contents, YAML front matter, mentions, LaTeX math, emoji shortcodes, or custom containers. If you need those, league/commonmark is the right choice. It's the most featureful pure-PHP option and actively maintained. Speed doesn't help if the feature you need isn't there.

Compatibility

mdparser builds and tests on PHP 8.3, 8.4, and 8.5 across Linux (x86_64), macOS (arm64/x86_64), and Windows (x86/x64, both TS and NTS). CI runs on all three platforms, with an ASAN job on Linux to catch memory issues. Pre-built Windows DLLs ship with each GitHub release.

Installation

pie install iliaal/mdparser

PIE handles the download, phpize, configure, make, and install. On a minimal PHP image you'll need git, bison, and libtool-bin as build dependencies.

From source:

git clone https://github.com/iliaal/mdparser.git
cd mdparser
phpize && ./configure --enable-mdparser
make -j && sudo make install

php_excel 2.0: The C Extension for Excel That PHP Should Have Had All Along

Ilia Alshanetsky — Mon, 04 May 2026 18:28:22 +0000

PHP processes more Excel files than any language except maybe Python. Payroll exports, inventory imports, financial reports, data migrations. If your business runs on spreadsheets (and it does), your PHP app touches them constantly.

The standard approach is PhpSpreadsheet: a pure-PHP library that parses XML, builds an in-memory object graph, and promptly devours your server's RAM. It works fine for small files. It falls apart the moment someone uploads a 50,000-row export from SAP. (Don't ask me how I know. 😢)

php_excel takes a different path. It's a PHP extension that wraps LibXL, a commercial C/C++ library purpose-built for reading and writing Excel files. Unlike most alternatives, LibXL handles both modern xlsx (Office 2007+) and the legacy xls binary format (Excel 97-2003), so you don't need separate codepaths for old and new files.

Instead of parsing XML in userland PHP, every cell read and write is a single C function call. In my benchmarks it's 7-10x faster than PhpSpreadsheet, and its memory footprint stays flat while PhpSpreadsheet's climbs past a gigabyte.

Version 2.0 shipped on April 5, 2026. It's the first major release in a long while, and it brings the extension fully into modern PHP.

What Changed in 2.0

The last official release (1.0.2) dates back to 2016. There was an unreleased 1.0.3 with PHP 7 support contributed by community members a few years later, but it never shipped. PHP has changed a lot since then. 2.0 is a ground-up modernization:

PHP 8.3 is the minimum version. Full support for 8.4, 8.5, and the development master branch. The extension builds and tests clean against all four, with zero warnings. On the LibXL side, the minimum is 4.6.0 (released over a year ago), with support up to the latest 5.1.0. I gate newer LibXL features at compile time: you get everything your installed version supports, and the extension still builds clean against 4.6.0.

2.0 adds six new classes to the existing six:

ExcelRichString: mixed-font text in a single cell (bold the header, italicize the footnote)
ExcelFormControl: checkboxes, dropdowns, spinners, buttons, and other form widgets
ExcelConditionalFormat / ExcelConditionalFormatting: conditional formatting rules and their application to cell ranges
ExcelCoreProperties: workbook metadata (title, author, creation dates, categories)
ExcelTable: structured table support for xlsx

I added methods across every existing class. ExcelBook now handles rich strings, conditional formats, VBA removal, DPI awareness, and picture-as-link support. ExcelSheet got pixel-based column/row sizing, tab colors, active cell management, selection ranges, form controls, data validation, and structured tables.

Every parameter and return type now has proper arginfo. That's 399 typed parameters and 277 typed return values, which means IDE autocompletion and static analysis tools actually work with the extension.

I also cleaned up the internals. Constructors now throw exceptions on error instead of silently returning false. I fixed several use-after-free bugs, null pointer dereferences, and memory leaks, the kind of issues that only surface under heavy load or with AddressSanitizer enabled. Serialization is disabled on all classes (serializing a file handle was never going to end well). The full list is in the ChangeLog.

Why a C Extension?

PHP's process-per-request model means every request starts from scratch. When PhpSpreadsheet opens a 100,000-row file, it parses the underlying XML with SimpleXML (DOM-based, so the entire XML tree lives in memory), then builds a Cell object for every cell with coordinate indexes, style references, and type metadata. In my benchmarks, PhpSpreadsheet 5.5 used about 1,066 MB to load 2 million cells, roughly 0.5 KB per cell for the object graph alone. That's already over a gigabyte for a single 100,000-row sheet. Add formatting, and it climbs further.

LibXL does the same work in optimized C/C++. The XML parsing, ZIP decompression, and cell storage all happen in native code. The extension itself is a thin translation layer: it takes PHP zvals, converts them to C types, calls the LibXL function, and converts the result back. The overhead per cell is a few hundred nanoseconds.

LibXL still uses real memory on the C heap for its internal workbook structures, so this isn't a free lunch. But it uses that memory more efficiently than PhpSpreadsheet's PHP object graph, and it's close to an order of magnitude faster.

Benchmarks

I ran these on PHP 8.4.19 (release build, NTS) against PhpSpreadsheet 5.5.0. Each test writes or reads a mix of integers, floats, and strings across 20 columns. Same data, same machine, measured with hrtime().

Here's the php_excel write test:

$book = new ExcelBook(null, null, true); // xlsx mode
$sheet = $book->addSheet('Bench');

for ($r = 1; $r <= $rows; $r++) {
    for ($c = 0; $c < $cols; $c++) {
        if ($c % 3 === 0) {
            $sheet->write($r, $c, $r * $cols + $c);        // integer
        } elseif ($c % 3 === 1) {
            $sheet->write($r, $c, "Row{$r}_Col{$c}_Text");  // string
        } else {
            $sheet->write($r, $c, $r * 1.5 + $c * 0.3);    // float
        }
    }
}
$book->save($outFile);

And the PhpSpreadsheet equivalent:

$spreadsheet = new Spreadsheet();
$sheet = $spreadsheet->getActiveSheet();

for ($r = 1; $r <= $rows; $r++) {
    for ($c = 1; $c <= $cols; $c++) {
        if (($c - 1) % 3 === 0) {
            $sheet->setCellValue([$c, $r], $r * $cols + $c);
        } elseif (($c - 1) % 3 === 1) {
            $sheet->setCellValue([$c, $r], "Row{$r}_Col{$c}_Text");
        } else {
            $sheet->setCellValue([$c, $r], $r * 1.5 + $c * 0.3);
        }
    }
}
$writer = new Xlsx($spreadsheet);
$writer->save($outFile);

Write results (time / total process memory via VmPeak):

Rows	Cells	php_excel	PhpSpreadsheet	Speed
1,000	20K	0.05s / 85 MB	0.45s / 162 MB	10x
10,000	200K	0.55s / 153 MB	4.59s / 282 MB	9x
50,000	1M	2.72s / 508 MB	24.7s / 790 MB	9x
100,000	2M	5.37s / 908 MB	51.1s / 1,415 MB	10x

All memory figures are total process RSS (VmPeak from /proc/self/status), including the C heap. LibXL does use real memory for its internal structures, so php_excel isn't "free" on that front. But even counting everything, it uses 40-65% of what PhpSpreadsheet needs and finishes 9-10x faster.

One practical detail: PHP's memory_get_peak_usage() reports 2 MB for php_excel throughout, versus 1,254 MB for PhpSpreadsheet at 100K rows. LibXL allocates on the C heap, invisible to PHP's memory manager and memory_limit. If your PHP-FPM pool has a 128 MB memory_limit, PhpSpreadsheet will OOM on a 10K-row file. php_excel won't.

Read results (time / total process memory via VmPeak):

Rows	Cells	php_excel	PhpSpreadsheet	OpenSpout
1,000	20K	0.05s / 83 MB	0.39s / 175 MB	0.16s / 126 MB
10,000	200K	0.47s / 144 MB	3.74s / 578 MB	1.48s / 130 MB
50,000	1M	2.60s / 422 MB	20.1s / 2,317 MB	8.00s / 130 MB
100,000	2M	5.19s / 767 MB	40.8s / 4,501 MB	16.6s / 130 MB

Three different profiles. php_excel is fastest but uses memory proportional to the file (LibXL loads the whole workbook). PhpSpreadsheet is slowest and its memory explodes, 4.5 GB for 100K rows. OpenSpout streams row by row, so memory stays flat at 130 MB regardless of size, but it's 3x slower than php_excel.

To be fair to PhpSpreadsheet: it's the most feature-complete pure-PHP Excel library. If you don't need a C extension and your files stay under a few thousand rows, it works fine. Past that, it doesn't.

OpenSpout fills a different niche. It can't do random cell access, conditional formatting, formulas, rich text, form controls, or xls format. If your workload is "read CSV-like data from xlsx," it's a good free choice. If you need actual Excel features, it won't help.

php_excel gives you C library speed with the full Excel feature set. The tradeoff: LibXL requires a commercial license, and installing a C extension takes more effort than composer require. Whether that tradeoff makes sense depends on your workload. If you're generating a 200-row report once a day, PhpSpreadsheet is fine. If you're processing bulk imports, financial data, or anything where users upload files of unpredictable size, the C extension pays for itself quickly.

Code Examples

Creating a workbook and writing data:

$book = new ExcelBook();
$sheet = $book->addSheet('Sales Q1');

// Headers
$boldFont = new ExcelFont($book);
$boldFont->bold(true);
$headerFormat = new ExcelFormat($book);
$headerFormat->font($boldFont);

$headers = ['ID', 'Date', 'Customer', 'Amount', 'Status'];
foreach ($headers as $col => $header) {
    $sheet->write(1, $col, $header, $headerFormat);
}

// Data rows
$data = [
    [1001, '2026-03-15', 'Acme Corp', 15750.00, 'Paid'],
    [1002, '2026-03-16', 'Globex Inc', 8200.50, 'Pending'],
    [1003, '2026-03-17', 'Initech', 42000.00, 'Paid'],
];

$dateFormat = new ExcelFormat($book);
$dateFormat->numberFormat(ExcelFormat::NUMFORMAT_DATE);

$row = 2;
foreach ($data as $record) {
    $sheet->write($row, 0, $record[0]);
    $sheet->write($row, 1, strtotime($record[1]), $dateFormat, ExcelFormat::AS_DATE);
    $sheet->write($row, 2, $record[2]);
    $sheet->write($row, 3, $record[3]);
    $sheet->write($row, 4, $record[4]);
    $row++;
}

// Summary formula
$sheet->write($row, 3, '=SUM(D2:D4)');

$book->save('sales-q1.xlsx');

Reading an uploaded file:

$book = new ExcelBook();
$book->loadFile($_FILES['report']['tmp_name']);

$sheet = $book->getSheet(0);
$lastRow = $sheet->lastFilledRow();
$lastCol = $sheet->lastFilledCol();

for ($row = $sheet->firstFilledRow(); $row <= $lastRow; $row++) {
    $rowData = $sheet->readRow($row, 0, $lastCol);
    // process $rowData
}

Rich text in a single cell:

$book = new ExcelBook();
$sheet = $book->addSheet('Notes');

$richString = $book->addRichString();

$boldFont = new ExcelFont($book);
$boldFont->bold(true);

$richString->addText('Important: ', $boldFont);
$richString->addText('Review before end of quarter.');

$sheet->writeRichStr(1, 0, $richString);
$book->save('notes.xlsx');

Working with conditional formatting:

$book = new ExcelBook();
$sheet = $book->addSheet('Metrics');

// Write some data
for ($row = 1; $row <= 20; $row++) {
    $sheet->write($row, 0, rand(0, 100));
}

// Highlight cells above 75 in green
$cf = $book->addConditionalFormat();
$cf->font()->bold(true);
$cf->font()->color(ExcelFont::COLOR_GREEN);

$formatting = $sheet->addConditionalFormatting();
$formatting->addRange(1, 0, 20, 0);
$formatting->addRule(
    ExcelConditionalFormat::CELLIS,
    $cf,
    ExcelConditionalFormat::OPERATOR_GREATERTHAN,
    '75'
);

$book->save('metrics.xlsx');

Installation

Linux / macOS

First, get LibXL 4.6.0 or newer from libxl.com. It's a commercial library; there's a trial version that works without a license key (limited to ~300 cells and row 0 is inaccessible).

The easiest path is PIE (PHP Installer for Extensions), the official PECL replacement. I added PIE support as part of 2.0:

pie install iliaal/php-excel \
  --with-libxl-incdir=/opt/libxl/include_c \
  --with-libxl-libdir=/opt/libxl/lib64

Or build from source:

git clone https://github.com/iliaal/php_excel.git
cd php_excel
phpize
./configure --with-excel \
  --with-libxl-incdir=/opt/libxl/include_c \
  --with-libxl-libdir=/opt/libxl/lib64
make
sudo make install

Then add to your php.ini:

extension=excel.so

Make sure the LibXL shared library is in your linker path. Either install it to a standard location or set LD_LIBRARY_PATH:

echo "/opt/libxl/lib64" | sudo tee /etc/ld.so.conf.d/libxl.conf
sudo ldconfig

Windows

Pre-built DLLs for PHP 8.3 and 8.4 (both x64 and x86, TS and NTS) are attached to every GitHub release. Download the DLL matching your PHP version and architecture, drop it into your ext directory, and add to php.ini:

extension=excel

You'll also need libxl.dll from the LibXL Windows distribution placed somewhere in your system PATH, or in the same directory as php.exe.

License Key Configuration

If you have a LibXL license, store the credentials in php.ini rather than your source code:

[excel]
excel.license_name="Your Name"
excel.license_key="your-license-key-here"

The extension reads these automatically. Pass null for the license parameters in the ExcelBook constructor and they'll be picked up from the ini settings.

The extension is open source under the PHP-3.01 license. LibXL itself requires a commercial license for production use.

Source on GitHub. Issues, PRs, and stars welcome.

Teaching AI Agents How to Engineer

Ilia Alshanetsky — Sat, 02 May 2026 19:32:25 +0000

Every AI coding agent ships with the same problem: it knows syntax but not discipline. It can write a React component or debug a segfault, but it won't ask "did I verify this actually works?" before declaring victory. It won't split a 400-line diff into reviewable chunks. It won't check if the fix it's about to apply matches the root cause it claims to have found.

I've spent the past six months fixing that.

whetstone is a Claude Code plugin, and ai-skills is its portable counterpart for 35+ AI coding agents. Together they encode the engineering judgment that separates "code that compiles" from "code you'd ship."

What's in the box

The whetstone plugin ships 30 skills, 19 specialized agents, and 22 commands. Skills are compact instruction sets that fire based on what you're working on. Agents are purpose-built reviewers and researchers. Commands wire them into repeatable workflows.

The ai-skills repo extracts just the skills into a format any agent can consume: Claude Code (what I use), Codex, OpenCode, Cursor, Gemini CLI, Copilot CLI, and 35+ others. One install command, zero configuration.

# Portable skills for any agent
npx skills add iliaal/ai-skills

# Full plugin for Claude Code
/plugin marketplace add https://github.com/iliaal/whetstone
/plugin install whetstone@iliaal-marketplace

Skills aren't prompts

A skill looks like a markdown file. It acts like a behavioral contract.

Take the debugging skill. Its core rule: no fix until you've identified the root cause with file-and-line evidence, two levels deep in the call chain. The agent must reproduce the bug first, test one hypothesis at a time, and escalate to the user after three failed attempts instead of guessing forever.

The code-review skill runs a two-stage process: spec compliance first, then code quality. When a diff crosses three complexity thresholds (300+ lines, 8+ files, touches security or migrations), it dispatches parallel specialist agents. A security reviewer, a performance analyst, a database guardian, and a maintainability auditor all examine the same diff independently, then merge their findings with deduplication.

The writing skill maintains a kill-on-sight vocabulary list. "Delve," "leverage," "robust," "seamless," words that signal machine output. It catches structural tells too: forced triads, dramatic fragments, synonym cycling. Every piece of prose passes through a five-dimension scoring rubric before delivery.

These aren't suggestions. They're process gates. The agent can't skip them.

Good prompts still matter, though. Skills encode discipline, but the quality of what you ask for shapes the output just as much. I don't always get that right, so I built a refine-prompt skill that transforms vague instructions into precise, structured ones. It's the skill I use on my own prompts before committing them as commands or workflow steps.

How skills activate

Token budget matters. You don't always have a 1M context window, and even when you do, filling it with instructions leaves less room for the actual work. So I put real effort into compression.

At startup, only skill descriptions load into context. Each description is tuned to the minimum token count that still lets the agent match it to the right request. Too short and the skill never fires. Too long and you're burning context on 30 descriptions before the conversation starts. Finding that line took weeks of testing and iteration.

When your request matches a skill's keywords, the full body pulls in. Ask about a React component and the react-frontend skill fires. Start debugging and the debugging skill loads with its reproduction-first protocol.

The skills themselves follow the same principle. Core rules live in the SKILL.md body, kept under a 1K token target with a 2K hard cap. Detailed reference material, decision trees, pattern libraries, and extended examples go into references/ files that only load when the agent needs them. The code-review skill's security patterns, the debugging skill's competing-hypotheses framework, the writing skill's full banned-phrase list: all stored as references, pulled only when the agent needs them.

The plugin takes this further with a hook that intercepts agent dispatches. When the code-review command spawns a security-sentinel agent, the hook injects the relevant skills into that agent's context before it starts work. No manual invocation needed. Fresh agents inherit methodology on dispatch.

A three-tier priority system prevents overload: methodology skills (code-review, debugging) outrank domain skills (react-frontend, python-services), which outrank supporting skills (writing-tests, verification). Cap of five per injection. The agent gets exactly the discipline it needs without drowning in instructions.

The workflow loop

Five commands form the development cycle:

/ia-brainstorm interviews you one question at a time, produces two or three named approaches with trade-offs, and outputs a design document.

/ia-plan turns that into atomic tasks with specific file paths, phased into vertical slices capped at five to eight files each.

/ia-work executes the plan with task tracking, worktree isolation for parallel work, and verification gates after every task.

/ia-review runs the multi-agent code review described above.

/ia-compound captures the solution as searchable documentation in docs/solutions/, so the next time someone hits the same problem, a research agent finds it.

Each command works standalone. You don't need the full loop for a quick review or a focused debugging session.

There's a sixth command that sits outside the development cycle but drives the whole project forward: reflect. I run it after every big session. It walks through the full conversation, flags mistakes and friction points, identifies where skills fell short or triggered when they shouldn't have, and proposes fixes. Those findings feed directly into the next release: skill rewrites, hook regex tweaks to reduce false triggers, new memory entries so the agent doesn't repeat the same mistake twice. Most releases trace back to something /ia-reflect surfaced from a real session.

Built from real use, not theory

This isn't a weekend project that got a README. Six months of daily use, a release every few days, every change driven by something that broke or wasted my time in an actual session.

The code-review skill is diagnostic-only because auto-fixing introduced regressions. The debugging skill caps attempts at three because without that limit, agents would silently try 15 broken fixes before asking for help. The writing skill's banned-phrase list grows every time I catch the agent producing "in today's rapidly evolving landscape."

The plugin includes a skill distillery that automates this refinement loop. It harvests session logs from actual Claude Code usage, scores skill effectiveness via LLM-as-judge evaluation, and can evolve skills through DSPy optimization. A regression suite with 336 trigger-pattern fixtures gates every release. If a skill fires when it shouldn't, or doesn't fire when it should, the release fails.

What it covers

The skills span the stacks I work in and the problems I hit most:

Languages and frameworks: React 19 with App Router patterns, Node.js backend architecture (Express, Fastify, Hono), Python services with FastAPI, PHP/Laravel, Tailwind CSS, Rust, even Pine Script for TradingView.

Engineering process: planning with vertical slicing, code review with specialist dispatch, debugging with root-cause discipline, test writing, verification gates.

Infrastructure: PostgreSQL performance and schema design, Terraform, Linux/bash scripting, Docker, cloud architecture across AWS/Azure/GCP.

AI-native patterns: multi-agent orchestration, agent-native architecture audits, meta-prompting techniques, skill refinement workflows.

Each skill encodes opinions. The PHP skill mandates declare(strict_types=1) everywhere and PHPStan level 8+. The Node.js skill enforces layered architecture with no cross-layer HTTP imports. The React skill routes "should I use an effect?" questions through a decision tree that almost always answers "no." These aren't generic best practices scraped from documentation. They're the rules that prevent the bugs I've watched agents introduce.

Why portable skills matter

AI coding agents are proliferating. Most developers will use two or three over the next year, depending on context. Skills that only work in one tool create vendor lock-in for your engineering standards.

The ai-skills repo solves this. Install once, and your debugging discipline, review process, and code standards follow you across tools. The format is simple markdown with YAML frontmatter. Any agent that supports skill loading can consume them.

The whetstone plugin adds what only a deep integration can: agents that spawn other agents, hooks that inject context, commands that orchestrate multi-step workflows. If you're in Claude Code, you get the full system. If you're elsewhere, you still get the discipline.

Try it

# All skills (works everywhere)
npx skills add iliaal/ai-skills

# Just one skill
npx skills add iliaal/ai-skills -s code-review

# The full plugin (Claude Code)
/plugin marketplace add https://github.com/iliaal/whetstone
/plugin install whetstone@iliaal-marketplace

# Convert the plugin for Codex
git clone https://github.com/iliaal/whetstone
cd whetstone && bun install
bun run src/index.ts install ./plugins/whetstone --to codex

The Codex converter transforms agents into skills, commands into prompts, and rewrites Claude Code syntax into Codex equivalents. It outputs a .codex/ directory with everything mapped. The same CLI supports --to opencode and --also for multi-target conversion.

Both repos are MIT-licensed and on GitHub. The plugin ships weekly. The skills mirror syncs with every release.

Six months of daily use have taught me that AI agents don't lack capability. They lack process. Give them clear rules, verification gates, and escape hatches for when they're stuck, and the output quality jumps. That's what these projects encode, and they get a little better every week.

php_clickhouse 0.8.1: Three Releases Later, Stable

Ilia Alshanetsky — Fri, 01 May 2026 12:12:54 +0000

The launch post for php_clickhouse 0.6.0 covered the framing: native binary protocol, soft fork of the stalled SeasClick, modern ClickHouse types, 30-40% faster than HTTP at high throughput. That post landed April 25, 2026. Today (May 1, 2026) the current tag is 0.8.1, and I'm calling the extension stable.

The six days in between were a focused quality cycle, not a feature sprint. Three buckets:

Performance. Insert and write paths build native ClickHouse columns one at a time directly from row-major input. Peak intermediate PHP memory dropped from N_rows × N_cols zvals to one column.
Security. Strict full-consumption parsers across Map, narrow-int, Int128 / UInt128, geo, DateTime64, Time64, hex literals, and typed parameters. Wrong-type input throws instead of corrupting memory or coercing silently to zero. Recursive type-conversion gained a depth cap so adversarial server schemas can't blow the stack.
Stability. Per-Client state moved from file-scope std::map banks onto the zend_object itself. Unblocks ZTS, plugs leaks on bailout, fixes a refcount bug on the progress callback. Insert path recovers the native handle on every server-side rejection point so a thrown insert no longer wedges the connection.

Three releases (0.7.0, 0.8.0, 0.8.1) closed the API gap with the most-used HTTP client, refactored the extension's state model, hardened the insert surface, and surfaced one upstream UB fix that has since merged into clickhouse-cpp.

Here's the work.

0.7.0: Closing the Ergonomics Gap with smi2/phpClickHouse

The native binary protocol gives you 30-40% throughput. Most teams won't trade a familiar API for that, so the native client has to match the ergonomic surface of the most-used PHP HTTP client (smi2/phpClickHouse). 0.7.0 is the release that actually does that.

What landed:

setSettings(array) for client-wide ClickHouse settings (max_execution_time, max_memory_usage, async_insert). Per-call settings as a 5th array argument on select() / insert() / execute() / writeStart(). Per-call overrides global.
Server-side typed parameters via the {name:Type} placeholder syntax. Routed through Query::SetParam so the server quotes and parses according to the declared type. Plain {name} placeholders keep their existing client-side identifier-substitution behavior. Arrays format as ClickHouse array literals so Array(UInt32), Array(String) round-trip cleanly.
setProgressCallback(?callable) invoked for every Progress packet during a query (rows, bytes, total_rows, written_rows, written_bytes).
getStatistics() returning rows_read, bytes_read, total_rows, written_rows, written_bytes, blocks, rows_before_limit, applied_limit, elapsed_ms from the last completed query. Reset at the start of each query.
Structured ClickHouseException: server_code (e.g. 159 for TIMEOUT_EXCEEDED), server_name (DB::Exception), query_id. Populated on server errors and on any throw with a query-id context.
insertAssoc(table, rows) derives the column list from the keys of the first row.
SQL helpers: databaseSize(), tablesSize(), partitions(), showTables(), showCreateTable(), getServerUptime(). Each validates identifiers against the safe-character set.
Sub-second timeouts via connect_timeout_ms, receive_timeout_ms, send_timeout_ms config keys. Override the existing seconds-based keys when present.
Per-client query log accumulator: enableLogQueries(bool) toggles, getLogQueries() returns and clears. Each entry carries sql, query_id, elapsed_ms, rows_read, bytes_read, error_code, error_message.

The other under-the-hood change in 0.7.0 was migrating to a stub-driven arginfo workflow (clickhouse.stub.php → generated clickhouse_arginfo.h). Method parameter and return types are now declared at the engine boundary and visible to Reflection, IDEs, and static analyzers. Behavior is unchanged for correctly-typed callers; wrong-type callers now hit ZPP at the boundary instead of a custom thrown exception inside the method body.

None of 0.7.0 is novel on its own. The point is that without these the native client made you pay an ergonomics tax to get the speed. 0.7.0 settles that tab.

0.8.0: Per-Object State, ZTS, and Streaming

The 0.6.0 / 0.7.0 surface stored per-Client state in seven file-scope std::map<int, ...> banks keyed on Z_OBJ_HANDLE: the Client*, the in-flight insert Block, the ClientStats, the global settings, the progress and profile callbacks, the log toggle, the query log buffer.

That works, and it has three durability problems baked in:

No ZTS support. Threaded SAPIs share that file-scope state across threads. The 0.6.0 code gated MINIT with a hard error when --enable-zts was on. ClickHouse from RoadRunner / FrankenPHP / Swoole / php-pm was a non-starter.
Leaks on bailout. PHP's userspace __destruct doesn't run on fatal errors, so the map entries (and the underlying Client* and any half-open insert stream) leaked.
Refcount bug on the progress callback. A struct copy of the registered callable went stale when the calling scope went out of scope, and the next progress packet hit a freed zval.

0.8.0 moved the per-Client state onto the zend_object itself via custom create_object / free_obj handlers. The seven file-scope maps disappear entirely. ZTS gating at MINIT was deleted in the same release.

The refactor unblocks three things at once:

Threaded SAPIs. No global state to thread-isolate, so ZTS Linux is a first-class target now. CI grew a linux-zts job (PHP 8.4 ZTS built from source).
Cleanup on bailout. free_obj runs unconditionally, including on fatal errors. The Client* and any half-open insert stream get torn down properly.
The progress-callback fix lands. setProgressCallback now uses ZVAL_COPY instead of a struct copy, so the callable doesn't get freed out from under the next packet.

A Windows config.w32 shipped in the same release, rewritten from a 9-line warning stub to a full Windows build script that mirrors config.m4's source list and flags. Optional --enable-clickhouse-openssl plumbing is mirrored via CHECK_LIB("libssl.lib", ...). CI exercises Windows as a build + extension-load smoke test (no live ClickHouse on Windows yet).

Streaming reads

0.8.0 introduced two new read paths for result sets that don't fit comfortably in a single PHP array:

$it = $ch->selectStream("SELECT id, payload FROM events WHERE day = today()");
foreach ($it as $row) {
    process($row);
}

selectStream() returns a ClickHouseRowIterator (Iterator + Countable) that walks blocks lazily. The iterator survives unset($client) because blocks own their column data via shared_ptr.

For unbounded streams where you don't want to count or rewind:

$ch->selectStreamCallback(
    "SELECT id, body FROM events_unbounded",
    fn(array $row) => writeToS3($row),
);

The callback fires once per row as blocks arrive, never accumulating the full result.

The plain select() path is unchanged and remains the faster choice when you actually want a full PHP array. The streaming variants exist for the row-millions case where you don't.

Geo, LowCardinality(Nullable), and the Map matrix

The type surface expanded too:

Geo types Point, Ring, Polygon, MultiPolygon round-trip via ColumnGeo. Point as [Float64, Float64], the others as nested arrays.
LowCardinality(Nullable(String)) and LowCardinality(Nullable(FixedString)) round-trip on read and write.
The insert path now accepts any Map(K, V) over scalar K and V (String, all signed/unsigned integer widths, Float32/64, UUID) plus LowCardinality(String) keys and values. The read path mirrors the same matrix except for LowCardinality keys (vendor gap). Previously only five hardcoded combinations worked.
SimpleAggregateFunction(f, T) reads transparently as T.

Geo support unblocks one of the two large reasons people stayed on the HTTP client. The other was streaming.

Other 0.8.0 surfaces worth naming

selectStatement() returns a ClickHouseStatement result wrapper: Iterator, Countable, ArrayAccess, JsonSerializable, plus fetchOne() / fetchKeyPair() / fetchColumn() / toArray() / statistics(). Read-only (offsetSet / offsetUnset throw). Carries a per-call stats snapshot so it survives the client running other queries afterwards.
setVerbose(bool|callable) for protocol-level lifecycle tracing. Pass true for JSON lines on STDERR, or a callable invoked with ($eventName, $context). Events: select_start, data_block, select_finish, execute_start, execute_finish, server_exception. No-op when off, so the hot path stays cheap on production.
DDL helpers: isExists(), showDatabases(), showProcesslist(), getServerVersion(), tableSize(), truncateTable(), dropPartition(). All identifier args validated; dropPartition SQL-escapes the partition value.
Client introspection: resetConnection(), getServerInfo() (name, version, revision, timezone, display_name), getCurrentEndpoint() (host/port of the active endpoint when an endpoints[] pool is in use), setProfileCallback(), ping_before_query config key.
query_id echoed through getStatistics() so callers can correlate a stats snapshot to a server-side query in system.query_log.
smi2-style sugar: setSettings() returns $this for chaining, setSetting(key, value) for the single-key form, setDatabase(string) issues USE and updates the cached default used by databaseSize() / showTables(), getter aliases (getServerCode(), getServerName(), getQueryId()) on ClickHouseException.

IPv4 / IPv6 crash, fixed

This one's worth calling out as a bug-of-the-release. clickhouse-cpp v2.6.1 made ColumnIPv4 / ColumnIPv6 siblings of (not subclasses of) ColumnUInt32 / ColumnFixedString. The 0.6.0 / 0.7.0 read paths were doing As<ColumnUInt32>() / As<ColumnFixedString>() on IP columns, which now returned null instead of dispatching. The next dereference segfaulted the worker.

Fixed by switching to ColumnIPv*::AsString(row) for canonical dotted-quad / ::1 form. If you hit a crash on IP column reads pre-0.8.0, this is why.

Distribution: pre-built binaries via PIE

Binaries for Linux glibc (x86_64 + arm64) and macOS (x86_64 + arm64) are now available. On a supported platform the install collapses to one line:

pie install iliaal/php_clickhouse

No vendored clickhouse-cpp build, no abseil compile, no five-minute make. TLS still requires the source build (pie install iliaal/php_clickhouse --enable-clickhouse-openssl), but that's a smaller set of users.

0.8.1: The Insert Path That Recovers

0.8.0 was the architecture release. 0.8.1 was the hardening pass: nine rounds of reviewer-driven fixes, mostly on the insert and write surface plus the type-conversion boundary.

The headline bug:

ClickHouseException: cannot execute query while inserting

If a server-side insert rejection (missing table, bad column, CHECK constraint, schema drift) threw out of BeginInsert / SendInsertBlock / EndInsert, the vendored client's inserting_ flag stayed set. Subsequent select / execute on the same handle threw the message above until the caller manually called resetConnection().

0.8.1 wraps every server-side rejection point in a connection-reset-then-rethrow. Same handle stays usable.

Destructor cleanup mirrors the same dirty/clean recovery split: an in-flight streaming insert with sent blocks is dropped via ResetConnection on unset() rather than committed via EndInsert. Clean sessions still EndInsert. Avoids partial commits on script bailout.

Memory: column-at-a-time insert

Pre-0.8.1, insert() and write() materialized a full column-major PHP zval matrix from the user's row-major input before building the native ClickHouse columns. For a 1M-row × 30-column insert that's 30M zvals sitting in PHP memory while the column build runs.

0.8.1 builds native columns one at a time directly from the row-major input. Peak intermediate PHP memory drops from N_rows × N_cols to one column.

insertAssoc() benefited from the same change: no more positional copy of input rows. The column gatherer reads each column directly from the original associative rows, and key validation uses zend_hash_exists against the first row's HashTable instead of allocating a new std::string for every row key.

Strict parsers across the type surface

Map, narrow-int (Int8 / Int16 / Int32 / their unsigned siblings), Int128 / UInt128, geo, DateTime64, Time64 insert paths now use full-consumption strict parsers. Non-numeric strings, fractional doubles, non-finite floats, and out-of-range values throw instead of silently coercing to 0 / 0.0 inside the column.

UInt64 inserts gained a shared strict_zval_u64 parser that accepts decimal and hex strings above ZEND_LONG_MAX on both the scalar and Map(*, UInt64) paths. Reads continue to surface upper-half values as decimal strings.

The class of bug strict parsing eliminates is the worst kind of insert bug: the string "foo" lands in an Int32 column as 0, no error, no audit trail. Now it throws.

Validation and reentry

A few smaller fixes worth naming:

write() rejects rows narrower or wider than the writeStart column count. The previous path took the first row's element count as authoritative, so [1] against writeStart(t, ['a','b']) landed 1 into column a with b defaulted server-side.
insert() rejects rows with extra positional or named cells. A row like [1, 99] against a single-column table previously landed as 1 with 99 lost.
A failed later write() no longer commits previously sent blocks. The catch path tracks whether any block has been sent in the current writeStart() session and chooses ResetConnection (discard) over EndInsert (commit) on a dirty session.
insertAssoc() rejects integer-keyed later rows and any key-set drift from the first row. The first row defines the column set; every later row must match.
Enum8 / Enum16 inserts reject undeclared integers, NULL on non-Nullable columns, and unknown string names.
Single-token placeholder validator: {name} placeholders accept exactly one identifier and reject comma-separated lists. Comma-list callers must use array form.
Same-client reentry guard: a userland progress / profile callback that fires another query on the same handle now throws cleanly instead of crashing the worker on the next ReceiveData.
Recursive type-conversion depth cap (32) keeps deeply nested structures (Array(Array(...)), Map(K, Tuple(...))) from blowing the stack.

23 new PHPTs (072–094) pin all of the above.

Upstream: One Fix Merged Back to clickhouse-cpp 🎆

The ASan job added in 0.8.0 caught a latent UB in the vendored library that nobody had been hitting in production, but UBSan flagged on every empty LowCardinality(String) value:

runtime error: null pointer passed as argument 2,
  which is declared to never be null

ColumnStringBlock::AppendUnsafe was calling memcpy(pos, str.data(), str.size()) unconditionally. When str was constructed from an empty std::string, str.data() is allowed to be NULL, and libc declares memcpy's second argument with __attribute__((nonnull)) regardless of the size. Every libc no-ops memcpy(_, NULL, 0) in practice, so the bug was benign on real workloads, but the false-positive UBSan trip was noising the extension's ASan job and obscuring real findings.

Patch: guard the memcpy with if (str.size() > 0). Submitted upstream as clickhouse-cpp#489, merged 2026-04-27. The local patch in lib/clickhouse-cpp/LOCAL_PATCHES.md will drop the next time the vendored library bumps.

What's Still Missing

Two limitations carry forward from clickhouse-cpp v2.6.1:

SELECT ... WITH TOTALS and SETTINGS extremes=1 throw unimplemented 7 from the cpp layer. The vendored library does not dispatch the Totals / Extremes packet types (upstream issue #297). getTotals() / getExtremes() are deferred.
Map(LowCardinality(K), V) reads are not yet decoded by the vendored library (writes succeed). showProcesslist() selects a fixed projection of standard columns to avoid the unsupported Map columns (ProfileEvents, Settings, used_*).

If either blocks your workload, file an issue at github.com/iliaal/php_clickhouse with the schema and a minimal repro. Both are upstream and tracked.

The repo is at github.com/iliaal/php_clickhouse. Install via PIE: pie install iliaal/php_clickhouse (add --enable-clickhouse-openssl for TLS). The original launch post that framed the fork story sits at ilia.ws.

Driving TradingView Desktop From an AI Agent

Ilia Alshanetsky — Wed, 29 Apr 2026 22:11:00 +0000

Anyone who's tried AI-assisted trading research has hit the same wall.

The agent has no native access to your charts. You end up copy-pasting symbols, indicator values, screenshots, and Pine Script back and forth between TradingView and Claude or Cursor. The tools that try to fix this fall into two camps: route market data through a third-party API (added latency, added cost, their interpretation of your bars), or pollute your TradingView chart with helper indicators just so an agent can read them back.

There's a third path that's more obvious in retrospect: drive your local TradingView Desktop through the Chrome DevTools Protocol that the app already exposes on port 9222 when you launch it with --remote-debugging-port=9222. The agent talks to the same TradingView you already use, reads what your chart actually shows, executes Pine Script through TradingView's own runtime. Same data, same indicators, same features, just with an agent in the loop.

A project called tradesdontlie/tradingview-mcp started down this path. Then it stalled with TV Desktop 3.1.0 incompatibilities and a handful of bugs, and the maintainer went quiet on PRs. I forked it, and now 71 commits later just tagged 1.0.0 of the fork. This post covers what I added and what the tool doesn't do.

What's in 1.0.0

The release is at https://github.com/iliaal/tradingview-mcp/releases/tag/1.0.0 with the per-tool changelog. The high-level numbers:

78 → 96 tools (18 new MCP tools)
A tv CLI (30 commands, 66 subcommands) mirroring the MCP surface
TV Desktop 3.1.0 compatibility across the whole surface
338 offline tests (pattern detection, multi-timeframe, replay, CLI routing)
Removed ui_evaluate from the upstream surface (it accepted arbitrary JavaScript in the user's authenticated TV session)

Pine Script Lifecycle

The original project let an agent inspect Pine Script, but only barely. Editing, saving, switching, and version history all required the user to click through TradingView's UI. The 1.0.0 fork closes that gap with eight new tools:

pine_save_as and pine_rename for naming and copying scripts
pine_version_history, pine_delete, pine_switch_script for managing the Pine library
pine_smart_compile (auto-detects whether to add or update an indicator on the chart; returns elapsed_ms)
pine_analyze (offline static analysis; catches typos, unused vars, deprecated patterns before compile)
pine_check (server-side compile without putting the script on a chart; useful for CI-style validation)

The pine_check + pine_analyze pair is the unlock for AI-assisted Pine debugging. The agent writes a draft, runs pine_analyze for cheap structural checks, then pine_check for the real compile, reads errors, fixes, repeats. The user never has to add an unfinished script to the chart just to see whether it compiles.

Pine Drawing Readers

This is the part I keep using most. Five new tools let the agent read what a Pine indicator actually drew, after it's running on the chart:

data_get_pine_lines: horizontal price levels (support, resistance, trend lines)
data_get_pine_labels: text annotations (signal labels, divergence callouts)
data_get_pine_tables: table cells (stats panels, multi-symbol scanners)
data_get_pine_boxes: price zones (supply, demand, order blocks)
data_get_pine_shapes: plotshape and plotchar markers

Default behavior deduplicates and caps output (50 labels by default). Override with verbose=true or max_labels=N for cases where the agent needs the raw set.

Why this matters: agents writing Pine Script could previously check whether the script compiled, but couldn't verify whether the logic was correct. Now the agent can write an indicator, compile it, and read the labels back to confirm the right bars were tagged. Without this, AI-assisted Pine work stops at "syntax is fine, hope you wrote what you meant."

This also replaces the workflow that an agent would otherwise fall back to: screenshot the chart, run OCR over the image, hope the agent pieces together what the indicator drew. That path is slow (a screenshot round-trip plus OCR latency on every read), unreliable (overlapping labels and thin lines confuse the OCR), and expensive (chart images in the agent's context burn thousands of tokens before any reasoning happens). The structured readers skip all three problems.

Multi-Pane and Tab Navigation

Pine indicators rarely live alone. A real chart layout might have three panes (price + RSI + volume) and four tabs, one per ticker. The original project assumed a single chart context. The fork adds eleven tools that make the layout addressable:

pane_list, pane_focus, pane_set_layout, pane_set_symbol, pane_set_timeframe
pane_read_batch (single call that reads across all visible panes)
tab_list, tab_new, tab_close, tab_switch, tab_switch_by_name

pane_read_batch was the practical motivator: agents that need to compare indicator values across panes used to need 5+ round-trips. The batch reader collapses that to one CDP call, which matters when the agent is iterating quickly.

A non-obvious detail: pane focus needs a 300ms wait after pane.focus() for _activeChartWidgetWV to update, required since TV 3.1.0. The fork bakes this in so users don't have to discover it.

Multi-Timeframe and Pattern Detection

data_get_multi_timeframe reads indicator values across a list of timeframes (W → D → 4H → 1H → 15m alignment) in one call. It saves and restores the original timeframe, so the agent gets multi-timeframe context without disrupting the user's view.

data_detect_candlestick_patterns runs 17 classic patterns over raw OHLC bars: doji, hammer, hanging_man, inverted_hammer, shooting_star, marubozu, spinning_top, bullish_engulfing, bearish_engulfing, bullish_harami, bearish_harami, piercing_line, dark_cloud_cover, morning_star, evening_star, three_white_soldiers, three_black_crows. Each match returns the pattern name, a direction (bullish/bearish/neutral), and a strength score.

The point of doing pattern detection natively, instead of via a Pine indicator overlay, is chart hygiene. Pattern detection informs the agent; the user never wants to see it plotted on the chart. Running it over OHLC bars directly means no Pine indicator gets added to the chart, no scripts get pushed to TV's Save dialog, and the user's chart stays clean.

The `tv` CLI

The MCP surface is meant for AI agents. But the same operations are useful from a shell, and shipping both interfaces from the same code path (instead of building a separate CLI program) keeps them in sync.

tv ships 30 commands with 66 subcommands. A few examples:

tv quote get AAPL                          # current quote
tv data ohlcv AAPL --tf 1H --bars 200      # OHLCV bars
tv pine check ./my_indicator.pine          # offline compile
tv pine smart_compile ./my_indicator.pine  # add or update on chart
tv hotlist volume_gainers --country US     # scanner
tv stream all                              # poll-and-diff JSONL output

tv stream polls the chart and emits JSONL whenever something changes: a new bar, an indicator value update, a new label drawn. Useful for piping into tail-and-watch workflows or for sanity-checking a strategy as it runs.

Cross-Platform Launch

tv_launch auto-detects native macOS, Linux, Windows, and Windows MSIX (Microsoft Store) installs of TradingView Desktop, resolves Windows paths correctly when invoked from WSL2, and handles the case where a binary refuses --remote-debugging-port from a direct spawn. macOS Electron 38 is the worst offender there; the fix is to fall back to open -a with the port flag in --args.

The motivation for sinking this much code into launch behavior is operational: in a CI-like setup or a containerized agent loop, you want tv_ensure to be a no-op when TV is already running and a clean launch when it isn't, on whichever OS the agent happens to be on. The original project assumed the user had TradingView running and never had to think about how it got there.

A Quiet Architectural Change

One refactor: per-call _deps dependency injection across ten core modules (chart, data, drawing, pane, pine, replay, ui, watchlist, alerts, capture).

Before: each module imported connection.js directly. State lived in module globals. Tests had to monkey-patch connection.js to swap CDP behavior.

After: each function accepts a _deps parameter, so the test harness passes in a mock CDP wrapper without touching globals. The installCdpMocks and mockEvaluateFromTable helpers in tests/helpers/mock-cdp.js give every test an isolated environment.

Practical result: 338 offline tests run in seconds without needing TradingView Desktop open. The previous test surface was much smaller because anything beyond a unit test required the real app running. The DI refactor unlocked the test count, which is what makes the 3.1.0 compat fixes safe to ship.

What Was Removed: `ui_evaluate`

The upstream had a tool called ui_evaluate that accepted arbitrary JavaScript and ran it in the authenticated TradingView session. Anyone with MCP access to the agent had effective full read/write access to the user's TradingView account state: watchlists, alerts, saved scripts, anything the session could see.

Dropped it. There's no use case for arbitrary JavaScript that isn't better served by a specific tool with a narrow boundary. If you need to read or modify something the existing tools don't cover, that's a missing tool, not a reason to expose the JS runtime.

What It Doesn't Do

The agent talks to your running TradingView Desktop via CDP. There's no API spoofing, no auth bypass, no headless TV. If you don't have TV Desktop installed, the tool can't help you.

TradingView's free tier covers most of the lifecycle tools. Some features need paid tiers (multi-pane, replay mode, second-resolution data, more indicators per chart). The tools wrap whatever the local TV exposes; they don't unlock features you don't have.

It doesn't bypass anything. It doesn't get you data TradingView doesn't already give you. The improvement is the agent surface, not the data access.

Install

git clone https://github.com/iliaal/tradingview-mcp
cd tradingview-mcp
npm install

Add the server to ~/.claude/.mcp.json (or your MCP config). Launch TradingView with --remote-debugging-port=9222. The README has the paste-into-Claude-Code one-liner that covers the agent-side wiring.

It's Alive! statgrab Returns After 20 Years

Ilia Alshanetsky — Tue, 28 Apr 2026 21:15:29 +0000

In 2005 I wrote a PHP binding for libstatgrab and pushed it to PECL. The extension took CPU, memory, disk I/O, network, process, and user statistics from a cross-platform C library and exposed them to PHP as plain functions. I moved on to other things, libstatgrab kept evolving, PHP went through three major versions, and the binding sat untouched. By 2020 you could not build it against PHP 7 without patches. By PHP 8 it was effectively gone.

statgrab 2.0 brings it back. PHP 8.0 through 8.5, libstatgrab 0.92+, glibc Linux, musl, macOS, FreeBSD. The 2006 procedural API still works (sg_cpu_percent_usage, sg_memory_stats, sg_diskio_stats), there is a modern OO surface (Statgrab::cpu(), Statgrab::memory(), Statgrab::processes()), counters return as 64-bit int instead of the 2006 stringified %lld, and the BC bugs that were latent in the original (swapped page-stat keys, copy-pasted gid/egid fields, the flat name_list for users) are fixed.

A few things had to change to get there. One of them was upstreaming a memory leak fix to libstatgrab itself.

Why bring it back at all

I do not pull old extensions forward by default. I learned why with lchash.

lchash is another extension I originally pushed to PECL in 2005: a string-keyed hash table for PHP, designed around the idea that PHP's array implementation, while general, carried ordering and bucket-reallocation overhead that pure key-value workloads did not need. Tighter memory footprint, faster lookup, simpler semantics ("first writer wins" like glibc hsearch(ENTER)).

I shipped a 1.0.0 modernization this week. Rebuilt the storage on top of klib khash, got it green on PHP 7.4 through 8.5 NTS and ZTS, added a proper OO surface (LcHash with $obj[$key] dimension access), wrote a benchmark script and let it run.

The numbers were not flattering. On a release build of PHP 8.4 NTS, glibc Linux x86_64, lchash takes 1.4x to 1.7x longer to insert and around 2x longer to look up than a native PHP array, at 10k, 100k, and 1M entries. That gap is structural. The PHP 7 array rewrite (Dmitry Stogov's packed-array work) and the 8.x JIT with inline caching produced a hash table the runtime treats as a first-class type, with opcode-level array-access specialization that no extension can match.

The flip: lchash uses 40 to 80 percent of the memory PHP arrays do at the same entry count, because keys and values are stored as refcount-shared zend_strings with no per-entry Bucket overhead. That makes the extension a real win for memory-tight workloads (a long-running CLI worker holding hundreds of thousands of small mappings), and it still has the legacy-compat and C-porting use cases it had in 2005. For general code, the answer is "just use a PHP array."

I shipped lchash 1.0.0 anyway, with the benchmark table at the top of the README and the use cases honestly scoped. The lesson is not "do not revive things." It is: the revival has to be honest about what changed underneath. PHP arrays grew up. lchash now competes on memory, not speed, and the README says so before anyone has to find out.

statgrab is not in that situation. PHP 8 arrays are not a substitute for cross-platform system stats. The choice today, for someone running PHP on a server who needs CPU, memory, or disk numbers, is still one of:

Shell out to w, vmstat, df, ps and parse output that drifts between OS versions. fork+exec overhead per call.
Read /proc by hand. Linux-only, format keeps shifting between kernel releases, every file (meminfo, loadavg, diskstats, net/dev) has its own quirks.
Run a separate stats daemon (collectd, telegraf, node_exporter) and hit it over a socket. Adds a process and a network hop.

libstatgrab is the right primitive for option 4: a single C library that handles the per-OS path internally (Linux /proc, FreeBSD kvm, macOS host_* APIs) and exposes one typed surface. It has been in the Debian, Ubuntu, FreeBSD, and Homebrew package repositories for fifteen years. It just needed a PHP binding that worked on a current interpreter.

What modernization meant in practice

The 2006 binding was written against PHP 5, Zend 1, and 32-bit long. Most of the rewrite is mechanical: convert TSRM-style globals, replace Z_LVAL_PP patterns, switch to the typed parameter parsing macros. The non-mechanical parts were the BC quirks of the original API.

Four bugs were latent in the 2006 release.

Stringified counters. Memory totals, filesystem sizes, and CPU jiffies were returned as PHP strings. The reason was that 32-bit PHP could not hold a uint64_t, so the binding called snprintf("%lld", value) and shoved the string into a zval. Modern PHP runs on 64-bit zend_long. The 2.0 release returns these as plain integers. Callers comparing against numeric thresholds (if ($mem['total'] > 1_000_000_000)) now work correctly without an intval() wrapping every read.

Swapped page-stat keys. sg_page_stats() returned pages_in and pages_out swapped. Anyone who used the function and noticed inverted memory pressure curves probably worked around it locally. Fixed in 2.0.

gid and egid were copies of uid and euid. A copy-paste in the 2006 process-stats handler. Anyone filtering by group ID had been getting user IDs back. Fixed.

sg_user_stats() returned a flat list of usernames. This one is a libstatgrab change, not just a binding fix. The old library exposed a name_list array; the new library returns per-user records (login name, device, PID, login time, hostname). The new shape is strictly more useful. Callers reading name_list migrate to reading login_name from each record.

The full BC catalog is in the README. None of these are surprises if you read the libstatgrab CHANGELOG; they are surprises only if you remember the 2006 binding from when you last used it.

The leak I didn't expect

While running the new test suite under AddressSanitizer, statgrab's process-exit path leaked memory. Several allocations from libstatgrab's internal structures were never freed when the library shut down.

This is the kind of leak that does not matter for a long-running CLI process and does not show up in a typical request-response PHP cycle (the SAPI tears down the heap on each request). It matters for ASan-clean test runs, for valgrind-clean integration tests, and for anyone embedding libstatgrab in a long-lived process where shutdown order matters.

I traced it into libstatgrab itself. The library has a sg_shutdown() function but several globals were not on the cleanup path. I wrote the patch and submitted it upstream against libstatgrab 0.92.1; it is pending review. The libstatgrab release cadence is slow regardless, so the statgrab repo carries a vendored copy of libstatgrab 0.92.1 with the local patch documented under vendor/libstatgrab/LOCAL_PATCHES.md in the meantime.

If you build with --with-statgrab=bundled:

(cd vendor/libstatgrab && ./configure --enable-static --disable-shared --without-ncurses --with-pic && make)
phpize
./configure --with-statgrab=bundled
make

The resulting statgrab.so has no runtime dependency on libstatgrab.so. It links the patched copy in statically. For containerized or shared-hosting deployments this matters: you do not need to install libstatgrab on the target system, and you do not pick up whatever version the package manager happens to have. Once libstatgrab cuts a release with the patch, the bundled tree gets dropped or pinned to the released tarball.

The legal bookkeeping: vendored libstatgrab stays LGPL 2.1+, the extension code stays PHP-3.01. Static linking does not infect the extension because LGPL explicitly permits this with the standard provisions; the LICENSE files document both.

Cross-platform is the actual feature

Most of the value is right here. The same PHP code that reads CPU usage on a glibc Linux box reads it on Alpine, on macOS, on FreeBSD. No conditional based on PHP_OS, no different parser per platform, no surprise when an Alpine container behaves differently from the dev box because /proc/meminfo formatting differs.

libstatgrab does the per-OS adaptation in C, once, with tests. Linux uses /proc and sysfs. FreeBSD uses the kvm interface. macOS uses host_statistics(), host_processor_info(), the BSD-style sysctl tree. The binding is the same shape regardless. From the PHP side:

$cpu = sg_cpu_percent_usage();
$mem = sg_memory_stats();
$load = sg_load_stats();

Those three calls return populated arrays on every supported OS. There is no "if Linux, do this; else do that" in your code.

What you actually do with it

The thing PHP people kept asking me about, when statgrab existed in 2006, was health endpoints. A small JSON endpoint that returns CPU usage, memory pressure, and load average so the load balancer or the orchestrator can decide whether to send traffic. Today that is more often the job of a Prometheus exporter or a sidecar agent, but the in-process version still has its place: when the application itself wants to know its own state.

Concrete examples that come up:

A queue worker that throttles its concurrency when load average crosses a threshold.
An admin dashboard inside a long-running CLI tool showing live disk I/O and network throughput.
A test harness that asserts memory stays below a budget under a synthetic workload.
A graceful-shutdown hook that waits for filesystem buffers to flush before exiting.

For each of those, shelling out is wrong (latency and parser fragility), and pulling in a stats daemon is overkill. statgrab fits the gap.

$mem = sg_memory_stats();
$load = sg_load_stats();

if ($load['min1'] > 8 || $mem['used'] / $mem['total'] > 0.9) {
    $worker->throttle();
}

That is one library call per stat, no fork, no parsing. Same code on Linux, macOS, FreeBSD.

The OO surface is a thin layer for callers who prefer a class:

$sg = new Statgrab();
$top = $sg->processes(Statgrab::SORT_CPU, 10);
foreach ($top as $proc) {
    echo "{$proc['proc_name']}\t{$proc['cpu_percent']}%\n";
}

Install

PIE is the PHP Foundation's PECL successor and the recommended path on PHP 8.x:

pie install iliaal/statgrab

PECL still works for legacy installers:

pecl install statgrab

From source against system libstatgrab (Debian, Ubuntu, macOS via Homebrew, FreeBSD pkg) is documented in the README. The --with-statgrab=bundled path is for containerized environments and for picking up the unreleased leak fix.

The pitch

One library call instead of forking a process. One typed surface instead of a per-OS parser. The same PHP code reading CPU, memory, and load on Linux, macOS, and FreeBSD without conditionals.

That is what the 2006 extension was reaching for, on PHP and libstatgrab versions that were not quite there yet. Both have caught up. The binding is the missing piece.

If you run PHP on a server and have ever shelled out to w or parsed /proc/meminfo by hand, give it a look.

Repository: https://github.com/iliaal/statgrab

DEV Community: Ilia Alshanetsky

fastjson 0.3.0: A Faster Drop-In ext/json for PHP, Backed by yyjson

Why drop in faster JSON for PHP

What "drop-in" actually means here

The numbers

How the encoder gets to 6×

The memory tradeoff

Compat harness

Upstream collaboration with yyjson

Install

The four-character migration

fastchart 0.2.0: Native PHP Charts, Barcodes, and QR Codes in One Extension

Why charts in PHP again

What's in 0.2.0

Why barcodes and QR codes in a chart library

The compose path

Performance

Install

Twenty years later

mdparser: a native CommonMark + GFM parser for PHP

How it works

Performance

Feature comparison

What mdparser doesn't do

Compatibility

Installation

Links

php_excel 2.0: The C Extension for Excel That PHP Should Have Had All Along

Teaching AI Agents How to Engineer

What's in the box

Skills aren't prompts

How skills activate

The workflow loop

Built from real use, not theory

What it covers

Why portable skills matter

Try it

php_clickhouse 0.8.1: Three Releases Later, Stable

0.7.0: Closing the Ergonomics Gap with smi2/phpClickHouse

0.8.0: Per-Object State, ZTS, and Streaming

Streaming reads

Geo, LowCardinality(Nullable), and the Map matrix

Other 0.8.0 surfaces worth naming

IPv4 / IPv6 crash, fixed

Distribution: pre-built binaries via PIE

0.8.1: The Insert Path That Recovers

Memory: column-at-a-time insert

Strict parsers across the type surface

Validation and reentry

Upstream: One Fix Merged Back to clickhouse-cpp 🎆

What's Still Missing

Driving TradingView Desktop From an AI Agent

What's in 1.0.0

Pine Script Lifecycle

Pine Drawing Readers

Multi-Pane and Tab Navigation

Multi-Timeframe and Pattern Detection

The tv CLI

Cross-Platform Launch

A Quiet Architectural Change

What Was Removed: ui_evaluate

What It Doesn't Do

Install

It's Alive! statgrab Returns After 20 Years

Why bring it back at all

What modernization meant in practice

The leak I didn't expect

Cross-platform is the actual feature

What you actually do with it

Install

The pitch

The `tv` CLI

What Was Removed: `ui_evaluate`