php-spx: a PHP profiling extension with a built-in web UI

What php-spx solves, and who ends up using it

Profiling a PHP script usually means either editing the code to add instrumentation or attaching a separate launcher or browser extension. SPX takes a different route. The README describes it as a profiling extension that you switch on with an environment variable on the command line, or with a radio button in a web request, so no code changes are needed. It also states that Ctrl-C on a long running command line script is supported, which matters when the process you want to profile is one you would otherwise have to let finish.

The second problem it addresses is data locality. The README lists as a differentiator that SPX is "totally free and confined to your infrastructure (i.e. no data leaks to a SaaS)". For teams that cannot send profile payloads to a hosted service, that constraint alone decides the tooling.

The audience is therefore narrow and specific: PHP developers working on GNU/Linux, macOS or FreeBSD, on x86-64 or ARM64, who want a call stack level view of their own code without instrumenting it. The README is explicit that this is a non-production tool. It says you can "safely use it in a non-production environment" and labels the project experimental.

Why the full call stack changes what you can analyse

The README draws a direct comparison with Xhprof and its forks: those aggregate data per caller and callee pair, which the README says implies the loss of the full call stack and forbids timeline or Flamegraph based analysis. SPX keeps the stack, and that single design decision is what makes its three visualisations possible: a timeline that the README says scales to millions of function calls, a flat profile, and a Flamegraph.

Collection is metric-driven rather than fixed. The README states that 22 metrics are currently supported, covering time and memory, included files, objects in use, and I/O. Which ones you enable determines what the reports can show and, on GNU/Linux, whether SPX needs to read procfs. Selecting any of mor, io, ior or iow makes SPX read files under /proc for the current process or thread, which is where the PHP-FPM permission problem described below comes from.

Data flow is local throughout. The extension writes reports into an SPX data directory, and the web UI lists them and serves the analysis screens. The README notes that enabling profiling for all HTTP requests through the spx.http_profiling_enabled setting on a high-traffic environment "could quickly exhaust the storage device's capacity of the SPX's data directory". There is no sampling policy or retention rule documented in the README, so the data directory is something you manage yourself.

Installing php-spx and profiling a first web request

SPX needs a PHP development package matching your installed PHP version, plus the zlib development package. On Debian-based distributions the README gives this command:

sudo apt-get install zlib1g-dev

On Fedora-based distributions, including CentOS, AlmaLinux and Rocky Linux, the equivalent is:

sudo dnf install zlib-devel

The README offers two installation paths. The first is PIE:

pie install noisebynorthwest/php-spx

The second builds from source. Note that the README checks out a release branch rather than master:

git clone https://github.com/NoiseByNorthwest/php-spx.git
cd php-spx
git checkout release/latest
phpize
./configure
make
sudo make install

After that, add extension=spx.so to php.ini, or create a dedicated spx.ini file in the include directory. The README also suggests overriding the default configuration for a local development environment so that web requests can be profiled.

To reach the control panel, the README gives this URL, assuming your application is served at http://localhost:

curl --cookie "SPX_ENABLED=1; SPX_KEY=dev" http://localhost/

The browser equivalent is http://localhost/?SPX_KEY=dev&SPX_UI_URI=/. The README notes that the URL must be served by a PHP script through a normal web server feature such as a directory index or URL rewriting, and that SPX intercepts the request and disables the script's execution to serve its own content. If you get a blank page, the README says to set zlib.output_compression = 0 in your PHP configuration. Switch on "Enabled" in the form and profiling applies to the current domain and browser session through dedicated cookies. Refresh the request you want to profile, then refresh the control panel to see the report in the list.

Platform limits, ZTS caveats and the PHP-FPM permission trap

The README is unusually direct about platform support: "Platforms support is currently quite limited." The supported set is x86-64 or ARM64 on GNU/Linux, macOS or FreeBSD, with PHP 5.4 to 8.5. Windows is not in that list, and neither is 32-bit hardware. If your deployment target is outside that set, SPX is simply not available to you.

ZTS (multi-thread) PHP works, but the README lists three extra limitations and asks you to consider ZTS support "as still being in beta". First, a small overhead is added when SPX is loaded even if profiling is off. Second, Ctrl-C on a CLI script will not properly finish a profiling session, which removes one of the conveniences that makes the NTS build attractive. Third, segfaults are more likely than on NTS, and the README advises avoiding mixing SPX with other instrumenting extensions such as debuggers and profilers.

The PHP-FPM case is a concrete failure mode with a concrete fix. On GNU/Linux, the metrics mor, io, ior and iow are collected by reading files under /proc for the current process or thread. On most PHP-FPM setups the master process runs as root while children run as an unprivileged user, so the child cannot open a file under /proc/self. The README's answer is to add process.dumpable = yes to the FPM pool configuration. Without that line, those metrics will not work, and the error is a permission problem rather than a bug in the extension.

One more boundary: the README warns that enabling profiling at INI level for all HTTP requests on a high-traffic environment can exhaust the storage device holding the SPX data directory. Leaving profiling off by default and enabling it per session is the intended pattern.

php-spx versus Xhprof and Excimer

The README positions SPX against Xhprof directly, and the difference is architectural rather than cosmetic. Xhprof and its forks aggregate per caller and callee pair, which the README says loses the full call stack and rules out timeline and Flamegraph analysis. SPX stores the stack, so those views exist. If your question is "which functions dominate total time", either model can answer it. If your question is "what happened in this specific request, in order", the aggregated model cannot.

Excimer is a different kind of alternative, and one that appears in the related searches for this project. It is an instrumentation extension rather than a full report-driven profiler with a bundled UI, so the practical difference is what you get out of the box: SPX ships its own web UI with a control panel, a report list, and the three interactive visualisations, and the README links a live demo of the analysis screen. Choosing between them comes down to whether you want the collection and the viewing handled by one component, or whether you already have a reporting pipeline you would rather feed.

Tideways, also present in the related searches, is the hosted-service end of the spectrum. SPX's stated differentiator is the opposite: everything stays inside your infrastructure. That is a real trade-off. You give up whatever a managed service provides in exchange for not sending profile data anywhere, and you take on the data directory yourself.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-19. Releases are frequent and incremental: v0.4.20 in July 2025, v0.4.21 in October 2025, v0.4.22 later in October 2025. The version numbers stay in the 0.4 range, which is consistent with the README's statement that the project is experimental and that "API might change, features might be added or dropped, or development could be frozen".

That is the upgrade cost in one sentence. There is no documented stability guarantee for the configuration keys, the metrics list, or the report format. The README does not document a rollback procedure, nor does it describe a migration path between versions. A pinned version plus a test of your profiling workflow after each bump is the only defensible approach, and the README does not claim otherwise.

The licence is GPL-3.0, and the repository carries a THIRD-PARTY-LICENSES.md file alongside LICENSE. Because SPX is loaded as a PHP extension into the same process as your application, the usual question about linking and derivative works comes up. That is a question for your own legal review, not something the README answers. If you distribute a product that bundles the extension, read the licence text rather than assuming the answer.

Editorial conclusion

php-spx fits developers profiling their own PHP scripts on a local or staging machine, where the full call stack and the built-in web UI replace manual instrumentation. It is the wrong tool for production traffic, for Windows, for 32-bit hosts, and for anyone who needs a stable API, since the README calls the project experimental and says the API might change. Before adopting it, verify that your PHP version falls in the documented 5.4 to 8.5 range, that the zlib development package is installed, and, on PHP-FPM with I/O or memory metrics enabled, that process.dumpable = yes is set in the pool configuration.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. NoiseByNorthwest/php-spx on GitHub
4. README
5. Releases