Laravel Xhprof Laravel Package

Technical Evaluation

Architecture fit. The package is Laravel-native rather than bolted on. A service provider registers middleware into the HTTP kernel and listeners cover queue jobs and Artisan commands, so a single profile captures routing, middleware, controllers, Eloquent/query time, and view rendering in one call tree. For a TPM this is the difference between "the database looks fine" and a ranked list of named functions with wall time, CPU, memory, and call counts — the evidence needed to write a ticket like "reduce checkout p95 by 40%" instead of "improve performance."

The coverage beyond HTTP is the underrated half. In most Laravel applications the real cost sits in imports, nightly batches, and notification fan-out, not in the request path. Profiling those is what lets a TPM defend — or decline — infrastructure spend before approving bigger instances or more workers, with a number attached to the recommendation.

Three extension points matter for later leverage:

• ProfileSaved events — release markers, incident annotation, archival, without forking.
• Programmatic start()/stop() — performance assertions inside tests, the mechanism that turns an NFR from a wiki page into a merge gate.
• Needle-based URL skipping (v1.3.0) — excludes health checks, webhooks, and admin panels cleanly.

The honest boundary: this is point-in-time inspection, not observability. No RUM, no distributed tracing, no trend series, no alerting. Positioning it as "APM, but free" will not survive the first steering review.

Integration feasibility. Application-code footprint is genuinely small: composer require, publish config and migration, register middleware, enable the extension. No custom controllers, no routes, no external service. Realistically a one-sprint spike with same-day rollback. The gating question is not code — it is the runtime. XHProf (or tideways_xhprof) must be installed and enabled in both the web and CLI SAPIs; if the team does not control the PHP base image (shared hosting, locked managed runtime, extensions via support ticket), stop there rather than discover a silent no-op at sprint end.

Technical risk.

Key questions to resolve before committing.

1. Who controls the PHP image, and can the extension be enabled in both SAPIs this sprint?
2. Which named slow flow has an owner and an acceptance threshold? (No owner, no pilot.)
3. Where do profiles live — application DB or storage disk — and who owns retention/purge?
4. What is the sample rate on any environment with real traffic?
5. Can we get one CI performance assertion landed inside the pilot window, or is this tooling-without-a-gate?
6. If the maintainer stops shipping Laravel-major compatibility PRs, who forks and at what cost?
7. Does the organization already pay for an APM with staging code-level profiling? If yes, what does a second profiler in a different format buy?

Integration Approach

Stack fit. Correct fit is narrow and testable: Laravel 10–13.x, PHP runtime under your control, and a staging environment that mirrors production closely enough for profiles to transfer. It is not a fit for shared hosting or a locked managed runtime, and it is not a fit where a licensed APM already provides code-level staging profiles — the second profiler buys little and adds a training curve.

The package sits in the same layer as framework logging or a debug toolbar: it wraps the request lifecycle and produces local artifacts. It does not require an outbound network path, which is why it clears environments where a SaaS APM would need a security review and a procurement cycle. That is the practical reason to choose it for a timeboxed investigation.

Migration path. Two distinct paths, and the TPM should name which one is in play:

• Fresh adoption (most likely): Composer require, publish config and migration, register middleware early in the stack, enable the extension, set sample rate, write the prune job, run the acceptance test. Estimate: roughly an hour of engineering for baseline HTTP profiling, plus a day for job/command instrumentation and the CI assertion.
• Upgrade onto a pre-v1.0.10 install: the schema changed (id became the primary key, idcount removed). This is a migrate-again step, not automatic. Budget it explicitly and don't fold it into an unrelated release.

Rollback in both cases is Composer removal plus disabling the extension — same-day, no data loss risk beyond the profiles themselves. That low reversal cost is what makes a pilot approvable.

Compatibility. Release history shows steady Laravel-major tracking: 10 → 11 → 12 → 13 across v1.0.9, v1.1.0, v1.2.0, v1.3.0, with the compatibility PRs largely contributed via laravel-shift. The v1.3.0 release (2026-03-09) confirms current Laravel 13 support and added the URL-needle skip. Practical read: the project stays current on the framework dimension, and the compatibility work is being done by automated/community contributors rather than by the maintainer alone — mildly reassuring on bus factor, not a guarantee.

Pin the exact version. Treat "compatible with the next Laravel major" as an assumption to re-verify each upgrade cycle, not a standing property.

Sequencing. Four gates, each with a decision:

1. Pre-flight (½ day). Verify extension on both SAPIs. Confirm runtime control. Confirm Laravel version in the supported range. No-go here saves a sprint.
2. Staging pilot, HTTP only (1 sprint). Pick two revenue-critical flows. Install, set a sample rate, write the prune job, register middleware early. Exit criterion: profiles exist for both flows and the ranked hotspots are actionable.
3. Expand to jobs and commands. Explicit instrumentation. This is usually where the cost win actually lives — imports, batches, fan-out. Exit criterion: one job profiled and one measurable improvement shipped.
4. Add the merge gate. Land one CI performance assertion on a business-critical endpoint, with a named owner. This is the step that converts the tool from "installed" to "institutionalized"; skipping it is how the package becomes unused overhead.

Explicit non-goal throughout: production. Scoping it to local and staging is itself the product decision — it keeps overhead off the request path, avoids a retention argument, and keeps the "we need real APM" conversation honest and separate.

Operational Impact

Maintenance. Ongoing burden is small but not zero, and it should be named in the pilot readout rather than discovered later:

• Version pinning and upgrade review at each Laravel major. Cheap, but it needs an owner.
• Retention job. Non-optional. The runs table grows with traffic; without a prune routine it becomes a staging stability issue and a backup-time issue.
• Config drift. Sample rate and skip needles are the two settings that silently change overhead and data volume. Both belong in code review, not a dashboard.
• Bus-factor — the honest risk. 235 stars, effectively zero dependents, one primary maintainer. Mitigation is cheap: pin, vendor, and treat a fork as a day of work. Acceptable for internal staging tooling; not acceptable for anything on the production request path — which is exactly why the production boundary is part of the design, not a caveat.

Support. No commercial support, no SLA, no vendor relationship to escalate through. Support model is internal: whoever owns the pilot owns the knowledge. That is a real cost in an organization where tooling without a vendor "doesn't count" — anticipate it in the stakeholder conversation rather than arguing about it.

The counter-argument is the honest comparison: this package against a homegrown microtime() / DB::listen harness, or against nothing. An MIT package with Laravel 10–13 support that installs in about an hour is almost always the cheaper option for targeted internal investigation, and it avoids a procurement cycle entirely. Say that plainly; it is the strongest argument and it doesn't require overstating the tool.

Scaling. Two independent scaling concerns:

• Overhead on the request path. Controlled by sample rate and route skipping. For a timeboxed staging investigation, profiling every request on a handful of flows is fine. On anything high-volume, a sample rate is mandatory, not a tuning preference.
• Storage growth. Database storage is the default and creates a retention obligation. Disk storage removes it from the DB but not from disk. Either way, a prune job plus a documented retention window is a launch prerequisite for broad enablement — and a good pilot exit criterion to check explicitly.

Neither concern applies to production, because the tool shouldn't be there.

Failure modes. Ranked by how much damage they cause relative to how likely they are:

Note the shape of this list: every failure mode is cheap to detect and expensive to discover late. That asymmetry is the argument for the pre-flight gate and the acceptance test — both are hours, and both prevent a sprint of false confidence.

Ramp-up. The tool's learning curve splits into two separate skills, and the TPM should plan for both:

• Setup and plumbing (engineering, ~1 day). Composer, config, migration, middleware registration, extension enablement, prune job. Well-trodden; low risk.
• Reading a flame graph and turning it into a ticket (engineering + TPM, the real work). Inclusive vs. exclusive time, distinguishing framework overhead from application code, separating CPU from wall time from memory, and converting a hotspot into an estimable fix. This is where pilots stall: profiles get captured and nobody acts on them.

Mitigation for ramp-up is structural, not pedagogical: make the pilot exit criteria shipped fix with before/after numbers, not profiles collected. That single change makes the readout useful to stakeholders and forces the reading skill to develop on the first flow.

Pilot framing to stakeholders. Approve a timeboxed pilot: staging only, two flows, one sprint, one-page readout covering bottlenecks found, fixes shipped, and measured before/after. Approximately an hour of engineering plus an approved PHP extension and no license fee. It is not production monitoring and it will not page anyone; if RUM or cross-service tracing is needed later, that is a separate and larger buy — and this pilot is the cheapest way to scope that RFP with data from your own application rather than from a vendor demo.