Download the PHP package iliaal/statgrab without Composer

statgrab

A native PHP extension wrapping libstatgrab, the cross-platform system-statistics library. Originally released to PECL in 2006 against libstatgrab 0.6; the 2.0.0 line is a full modernization for the PHP 8.0+ era against libstatgrab 0.92+.

Supports PHP 8.0 through 8.5 on glibc Linux, musl, macOS, and *BSD.

The Problem

Reading system stats from PHP usually means one of three bad options:

• Shell out to top, vmstat, df, ps and parse the output. Fragile on every OS update, and fork/exec overhead adds up if you poll on a schedule.
• Read /proc by hand. Linux-only. Forces hand-rolled regex for every statistic, and the format drifts between kernel releases.
• Pull in a heavy monitoring framework. Overkill if all you need is a CPU number for a health endpoint.

libstatgrab is the right primitive: cross-platform, well-tested, in the package manager of every modern Unix. But the 2006 PECL binding has not shipped a PHP 8 build, and its 2006 BC quirks (stringified counters, swapped page-stat keys, a flat name_list for users) made the old extension awkward even when you could compile it.

✨ Key Features

⚖️ Why native

The case for a native extension is the failure modes of the alternatives:

• exec("top ...") and friends fork a process per call. The overhead is real if you poll every few seconds, and the output format drifts between OS releases.
• Hand-parsing /proc ties you to Linux and to whatever the kernel decided to print this year. Each file (/proc/meminfo, /proc/loadavg, /proc/diskstats, /proc/net/dev) has its own format and edge cases.
• Calling out to a stats daemon adds a network hop and a daemon to deploy.

statgrab calls libstatgrab in-process. libstatgrab handles the per-OS path (Linux /proc, FreeBSD kvm, macOS host_* APIs) and exposes a single typed surface. The extension wraps that surface with no allocation per call beyond the result array.

🚀 Quick Start

PIE (recommended on PHP 8.x)

PIE is the PHP Foundation's PECL successor. It installs from Packagist, builds against the active php-config, and produces a loadable .so. Make sure libstatgrab is installed first (see the From-source section below for the system package names), then:

Then add extension=statgrab to your php.ini.

PECL

The package remains in the PECL channel for legacy installers:

From source

Then add extension=statgrab to your php.ini.

config.m4 resolves libstatgrab through pkg-config first; if that fails it falls back to a path probe (/usr and /usr/local). Pass --with-statgrab=<prefix> to point at a custom install.

Bundled libstatgrab (statically linked, leak-fixed)

The repo carries a vendored copy of libstatgrab 0.92.1 under vendor/libstatgrab/ with one local patch (see vendor/libstatgrab/LOCAL_PATCHES.md) that fixes a process-exit leak upstream hasn't released yet. To use it:

The resulting .so has no libstatgrab.so runtime dependency.

The vendored libstatgrab tree stays LGPL 2.1+ (see LICENSE.libstatgrab); the extension code stays PHP-3.01 (see LICENSE). Dynamic-link or static-link, neither license infects the other.

API

Procedural

The 2006 function names are preserved.

CPU results (sg_cpu_percent_usage(), sg_cpu_totals(), sg_cpu_diff()) carry a previous_run key with the timestamp of the previous sample.

sg_diskio_stats() / sg_diskio_stats_diff(), sg_network_stats() / sg_network_stats_diff(), and sg_network_iface_stats() key rows by device/interface name; a duplicate name (multipath/LVM can repeat one) falls back to a numeric key instead of overwriting the earlier row.

Object-oriented

Class constants:

• Statgrab::DUPLEX_FULL | DUPLEX_HALF | DUPLEX_UNKNOWN
• Statgrab::SORT_NAME | PID | UID | GID | SIZE | RES | CPU | TIME
• Statgrab::STATE_RUNNING | SLEEPING | STOPPED | ZOMBIE | UNKNOWN
• Statgrab::CPU_PERCENT_ENTIRE | LAST_DIFF | NEW_DIFF — $source modes for cpu() / sg_cpu_percent_usage()
• Statgrab::HOST_STATE_UNKNOWN | PHYSICAL | VIRTUAL_MACHINE | PARAVIRTUAL_MACHINE | HARDWARE_VIRTUALIZED — interprets the host_state field on host() / sg_general_stats()
• Statgrab::FS_UNKNOWN | REGULAR | SPECIAL | LOOPBACK | REMOTE | LOCAL | ALLTYPES — bitmask values for the device_type field on filesystems() / sg_fs_stats()
• Statgrab::ERROR_NONE | INVALID_ARGUMENT | OPEN | OPENDIR | PERMISSION | UNSUPPORTED — most useful libstatgrab error codes for programmatic catches

Errors

Library-side errors emit E_WARNING with the libstatgrab error string and code, and the function returns false. The OO surface follows the same convention. Argument-count violations on no-arg functions throw ArgumentCountError per modern PHP convention.

sg_set_valid_filesystems() and Statgrab::setValidFilesystems() throw instead of warning on bad input: ValueError on an empty array or an entry containing NUL bytes, TypeError on a non-string entry. A libstatgrab runtime failure from the setter (or any other stat call) is the usual warning + false path — pair the false return with sg_error_details() / Statgrab::errorDetails() for the code, message, errno, and arg.

Notable 2.0 BC breaks

• sg_user_stats() returns per-user records, not a flat array of usernames. The underlying name_list field was removed from libstatgrab 0.91+. Migrate callers to read login_name from each record.
• Numeric counters (memory totals, fs sizes, jiffies) are returned as int instead of stringified numbers. The 2006 release stringified via snprintf("%lld") because 32-bit PHP couldn't hold them; modern 64-bit zend_long does. On 32-bit PHP builds these fields still truncate above 2^31; a 64-bit build is recommended.
• sg_page_stats() / sg_page_stats_diff() were swapped in 2006 and are now correct.
• sg_process_stats() fields gid and egid are now distinct from uid and euid (2006 had a copy-paste bug returning uid/euid for both).

See CHANGELOG.md for the full list.

🔗 Native PHP extensions

Companion native PHP extensions:

• php_excel: native Excel I/O via LibXL. 7-10× faster than PhpSpreadsheet, full XLS/XLSX with formulas, formatting, and styling.
• mdparser: native CommonMark + GFM markdown parser via md4c. 15-30× faster than pure-PHP libraries.
• php_clickhouse: native ClickHouse client speaking the wire protocol directly. Picks up where SeasClick left off.
• pdo_duckdb: PDO driver for DuckDB, analytical SQL in your PHP stack.
• fastjson: drop-in faster ext/json, backed by yyjson. 6× encode, 2.7× decode, 5× validate.
• phpser: decoder-optimized binary serializer for cache workloads. Faster than igbinary on packed numerics and DTO batches.
• fast_uuid: high-throughput UUID generation (v1/v4/v7), batched CSPRNG and SIMD hex formatter, ramsey-compatible API.
• fastchart: native chart-rendering extension. 38 chart types behind one fluent OO API, SVG-canonical with PNG/JPG/WebP and optional PDF output.
• phonetic: native phonetic name matching (Double Metaphone, Beider-Morse, Daitch-Mokotoff, NYSIIS, Match Rating), the encoders PHP core lacks.

License

PHP License 3.01.

Follow @iliaa on X • Blog

If this saved you from parsing /proc by hand, ⭐ star it!