Xh Tool Laravel Package

Technical Evaluation

Architecture fit. Despite being filed alongside Laravel/PHP packages, phperf/xh-tool is not a Composer package — it is a standalone Go CLI that parses XHProf profile payloads and renders call trees/graphs in a terminal. It sits at the operations layer, not the application layer: it consumes artifacts produced by the xhprof/tideways_xhprof PHP extension (file dumps) or the sibling xh-prof collector daemon over HTTP. Its role in a Laravel estate is "offline profiler viewer for engineers," not "library the app depends on." That is a legitimate but narrow fit, and it means composer require is not the integration path — binary distribution and instrumentation are.

Integration feasibility. The tool itself is trivially installable (single binary). The real work is upstream of it: compiling the XHProf extension into the PHP-FPM image, adding a sampling middleware to the Laravel HTTP kernel, and deciding where profile dumps live and for how long. None of that is hard, but it is all bespoke; the package contributes only the "read" half of the loop.

Technical risk. High relative to value. Last release March 2018, four stars, zero dependents — effectively unvetted and unmaintained. Primary risks: (1) no PHP 8.x-era validation, and XHProf output from community forks such as tideways/php-xhprof-extension may not parse identically; (2) a 2018 Go build likely predates modules and may not produce reliable darwin/arm64 artifacts for modern developer laptops; (3) no security advisory pipeline or maintainer to notify. A silent format mismatch is the dangerous failure — the tool exits cleanly with a plausible-but-wrong tree, which is worse than crashing.

Key questions. Which PHP runtime and extension version are we standardizing on, and does its output match what this parser expects? Do we need xh-prof as a server, or is file-dump mode sufficient? Is a GUI required for team-wide adoption (in which case xh-gui, XHProf UI, or Tideways is the real candidate)? What is our retention posture for profile artifacts, which can embed request-derived values and therefore PII?

Integration Approach

Stack fit. Additive and non-invasive. A Laravel middleware samples a small percentage of requests (1–5%), calls xhprof_enable()/tideways_xhprof_enable(), and writes the resulting array to object storage or a local volume. xh-tool then runs on demand against a chosen dump. No framework coupling, no service container bindings, no upgrade surface in composer.json.

Migration path. There is no migration — nothing existing changes. The strategic decision is build-vs-buy: Telescope and Debugbar already cover local development profiling, and Blackfire or Tideways cover production. Adopt xh-tool only if the team already has XHProf dumps and wants a zero-cost, offline, terminal-based viewer; otherwise it is a solution to a problem we do not have.

Compatibility. Version-pin everything: the PHP extension, the dump format, and the binary checksum. Validate parsing against a real dump from our exact extension build in a spike before committing to any workflow. Expect to compile the Go binary from source for current platforms, and treat that as a one-time cost we own.

Sequencing. (1) Spike on one non-production service: install extension, dump a profile, confirm xh-tool parses it. (2) Only on success, write the sampling middleware and config gate. (3) Define artifact storage, retention, and redaction policy. (4) Publish a one-page runbook. (5) Re-evaluate against Blackfire/Tideways before any broader rollout. Abort at step 1 if parsing is unreliable — the cost of stopping there is a day, not a sprint.

Operational Impact

Maintenance. Upstream is dormant, so we fork by default: vendored binary, pinned version, documented build command, named internal owner. The code surface is small, which makes us capable of maintaining it — but also means zero upstream fixes, including for parser bugs or Go/CVE rebuilds.

Support. No community, no issue velocity, no StackOverflow corpus. Internal documentation and a single knowledgeable engineer will be the entire support model. That is a bus-factor of one and should be treated as such in any adoption decision.

Scaling. The bottleneck is artifact storage, not the tool. Profiles are per-request and large; without sampling and short retention (hours, not days) storage cost grows linearly with traffic. The tool is inherently single-node and on-demand — it is not a profiling portal and should not be positioned as one.

Failure modes. Silent format drift producing incorrect trees; extension not loaded, yielding empty output that reads as "no hotspots"; OOM or long runtimes on oversized dumps; missing platform builds blocking laptop use. Instrument the pipeline to fail loudly — assert non-empty, well-formed dumps at write time rather than trusting a clean exit code.

Ramp-up. Engineers who already know XHProf's flat/tree semantics will be productive in under an hour. Everyone else will find terminal call graphs opaque; if the goal is broad team adoption of profiling, budget for a GUI-backed alternative instead.