PHPackages iliaal/statgrab - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. iliaal/statgrab ActivePhp-ext[Logging & Monitoring](/categories/logging) iliaal/statgrab =============== PHP extension wrapping libstatgrab, the cross-platform system-statistics library. CPU, memory, disk I/O, filesystems, network interfaces, processes, users. 2.2.0(1mo ago)10PHP-3.01CPHP >=8.0CI passing Since Apr 28Pushed 1mo ago1 watchersCompare [ Source](https://github.com/iliaal/statgrab)[ Packagist](https://packagist.org/packages/iliaal/statgrab)[ Docs](https://github.com/iliaal/statgrab)[ RSS](/packages/iliaal-statgrab/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)DependenciesVersions (2)Used By (0) statgrab ======== [](#statgrab) [![Tests](https://github.com/iliaal/statgrab/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/iliaal/statgrab/actions/workflows/tests.yml)[![Version](https://camo.githubusercontent.com/bd7024cf4b61c12bfbc90b3e3dd5accc6a237f4ba043dd8762cd81df5ed55988/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f696c6961616c2f7374617467726162)](https://github.com/iliaal/statgrab/releases)[![License: PHP-3.01](https://camo.githubusercontent.com/2d0c6e79d68e3ecde571be7a99c822e88c8379ff247dc40dddea7cad6872b8fb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d5048502d2d332e30312d677265656e2e737667)](http://www.php.net/license/3_01.txt)[![License: LGPL-2.1+ (vendored libstatgrab)](https://camo.githubusercontent.com/b010d2d3c8c38021627cb99a9808511237fcad7835326e5ddd484ca7c46b050e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76656e646f7265642d4c47504c2d2d322e312532422d626c75652e737667)](LICENSE.libstatgrab)[![Follow @iliaa](https://camo.githubusercontent.com/a54521c97521f05fbadec4bd9bcba96ff1eeaffe756a6d7338b47a628cdeb39b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f466f6c6c6f772d40696c6961612d3030303030303f7374796c653d666c6174266c6f676f3d78266c6f676f436f6c6f723d7768697465)](https://x.com/intent/follow?screen_name=iliaa) [![statgrab](images/statgrab-hero.jpg)](images/statgrab-hero.jpg) A native PHP extension wrapping [libstatgrab](https://libstatgrab.org), 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 ----------- [](#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 -------------- [](#-key-features) FeatureNotesCross-platformglibc Linux, musl, macOS, FreeBSDProcedural + OO API2006 `sg_*` function names preserved; modern `Statgrab` class on topBundled libstatgrab optionVendored 0.92.1 with a leak-fix patch; resulting `.so` has no runtime dependency on `libstatgrab.so`Modern typesCounters returned as 64-bit `int`, not stringified numbersModern PHP errors`E_WARNING` on library failure, `ArgumentCountError` for arg-count violationsBC-preserved 2006 namesDrop-in for callers of the original PECL extension, with the 2.0 BC notes documented belowโš–๏ธ Why native ------------- [](#๏ธ-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 ------------- [](#-quick-start) ### PIE (recommended on PHP 8.x) [](#pie-recommended-on-php-8x) [PIE](https://github.com/php/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: ``` pie install iliaal/statgrab ``` Then add `extension=statgrab` to your `php.ini`. ### PECL [](#pecl) The package remains in the PECL channel for legacy installers: ``` pecl install statgrab ``` ### From source [](#from-source) ``` sudo apt install libstatgrab-dev # Debian/Ubuntu # OR: brew install libstatgrab # macOS # OR: pkg install libstatgrab # FreeBSD phpize ./configure --with-statgrab make sudo make install ``` 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=` to point at a custom install. ### Bundled libstatgrab (statically linked, leak-fixed) [](#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: ``` (cd vendor/libstatgrab && ./configure --enable-static --disable-shared --without-ncurses --with-pic && make) phpize ./configure --with-statgrab=bundled make ``` 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 --- [](#api) ### Procedural [](#procedural) The 2006 function names are preserved. ``` sg_cpu_percent_usage(): array|false // user/kernel/idle/iowait/swap/nice (%) sg_cpu_totals(): array|false // cumulative jiffies + ctx switches/syscalls/IRQs sg_cpu_diff(): array|false // jiffies since last call sg_diskio_stats(): array|false // [diskname => [read, written, time_frame]] sg_diskio_stats_diff(): array|false sg_fs_stats(): array|false // mounted filesystems with size/used/inodes/... sg_general_stats(): array|false // os_name, hostname, uptime, ncpus, ... sg_load_stats(): array|false // min1, min5, min15 sg_memory_stats(): array|false // total, free, used, cache (bytes) sg_swap_stats(): array|false // total, free, used (bytes) sg_network_stats(): array|false // [ifname => sent/received/packets/...] sg_network_stats_diff(): array|false sg_page_stats(): array|false // pages_in, pages_out (cumulative) sg_page_stats_diff(): array|false sg_process_count(): array|false // total, running, sleeping, stopped, zombie sg_process_stats(?int $sort = null, int $limit = 0): array|false sg_user_stats(): array|false // [{login_name, device, pid, login_time, ...}] sg_network_iface_stats(): array|false // [ifname => {speed, duplex, active}] ``` ### Object-oriented [](#object-oriented) ``` $sg = new Statgrab(); $sg->cpu(); $sg->host(); $sg->memory(); $sg->processes(Statgrab::SORT_CPU, 10); $sg->disks(diff: true); ``` 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` The `SG_*` global constants from 2006 are still defined for BC. Errors ------ [](#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. Notable 2.0 BC breaks --------------------- [](#notable-20-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. - `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. ๐Ÿ”— PHP Performance Toolkit ------------------------- [](#-php-performance-toolkit) Native PHP extensions for the kinds of work pure-PHP libraries handle slowly: - **[php\_excel](https://github.com/iliaal/php_excel)**: Excel I/O via LibXL. - **[mdparser](https://github.com/iliaal/mdparser)**: CommonMark + GitHub Flavored Markdown via cmark-gfm. - **[php\_clickhouse](https://github.com/iliaal/php_clickhouse)**: native ClickHouse client via clickhouse-cpp. License ------- [](#license) [PHP License 3.01](LICENSE). --- [Follow @iliaa on X](https://x.com/iliaa) โ€ข [Blog](https://ilia.ws) If this saved you from parsing /proc by hand, โญ star it! ### Health Score 36 โ€” LowBetter than 79% of packages Maintenance91 Actively maintained with recent releases Popularity2 Limited adoption so far Community7 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 42d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2838354?v=4)[iliaa](/maintainers/iliaa)[@iliaa](https://github.com/iliaa) --- Top Contributors [![iliaal](https://avatars.githubusercontent.com/u/158724?v=4)](https://github.com/iliaal "iliaal (26 commits)") --- Tags libstatgrabmonitoringpeclphpphp-extphp-extensionphp-extensionspiestatgrabsystem-monitoringsystem-statisticsmonitoringsystemstatisticsphp-extensionpiepecllibstatgrab ### Embed Badge ![Health badge](/badges/iliaal-statgrab/health.svg) ``` [![Health](https://phpackages.com/badges/iliaal-statgrab/health.svg)](https://phpackages.com/packages/iliaal-statgrab) ``` ### Alternatives [rollbar/rollbar Monitors errors and exceptions and reports them to Rollbar 33724.4M84](/packages/rollbar-rollbar)[liip/monitor-bundle Liip Monitor Bundle 4738.9M19](/packages/liip-monitor-bundle)[datadog/php-datadogstatsd An extremely simple PHP datadogstatsd client 19026.4M15](/packages/datadog-php-datadogstatsd)[ekino/newrelic-bundle Integrate New Relic into Symfony2 28511.3M8](/packages/ekino-newrelic-bundle)[rollbar/rollbar-laravel Rollbar error monitoring integration for Laravel projects 14110.7M10](/packages/rollbar-rollbar-laravel)[slickdeals/statsd a PHP client for statsd 254.8M10](/packages/slickdeals-statsd) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)