Laravel Xhprof Laravel Package

Product Decisions This Supports

• Turning "the app is slow" into an estimable, prioritizable epic. A complaint like "checkout feels slow" has no acceptance criteria, so it can't be sized or slotted into a sprint. Profiling that flow returns a ranked list of hotspots — inclusive/exclusive wall time, memory, call counts, per function — for a single request, job, or command. That output is the acceptance criteria: it lets you file "reduce checkout p95 by 40% by fixing the N+1 in the pricing resolver" instead of "improve performance."
• Roadmap sequencing across competing performance asks. When three teams each want "performance work" this quarter, a profiling session on their flows tells you where the time actually goes. That supports defensible calls like "two of the five slow endpoints share one root cause; fix it once this sprint and defer the caching layer." It also gives you the evidence to decline work, which is often more valuable than approving it.
• Build vs. buy vs. do nothing on diagnostics. The honest comparison isn't this package against Datadog — it's this package against a homegrown microtime()/DB::listen harness, or against no instrumentation at all. An MIT package with Laravel 10–13 support and a roughly one-hour install is nearly always the cheaper option for targeted internal investigation, and it requires no procurement cycle or legal review to get started.
• Scoping infrastructure spend with data rather than instinct. If queue workers or nightly batches drive the hosting bill, a profile quantifies the win before you sign off on bigger instances ("70% of this job's runtime is serialization, not compute"). That's a cost-avoidance argument you can put on a slide, and it's the same artifact you'd need to justify not spending.
• Promoting performance from a wiki page to a merge gate. Because profiling is callable programmatically (start/stop from code), it can back CI and test assertions: "this endpoint stays under 300 ms," "this import handles N records under X seconds." That converts a non-functional requirement into a blocking check with a named owner instead of aspirational prose nobody enforces.
• Faster release triage. When a deploy "feels slower," a before/after profile of the same route resolves rollback-vs-hotfix-vs-accept in minutes rather than a day of speculation — and produces an artifact you can attach to the incident record.
• Scoping a future APM purchase. A timeboxed pilot on two or three flows tells you which flows deserve continuous monitoring. If you later go to market for real observability, you arrive with requirements derived from your own data rather than from a vendor demo.
• Deciding where profiling does not belong — as an explicit product decision. Scoping this to local and staging keeps overhead off the production request path, avoids a data-retention conversation about profile storage, and keeps the "we need real APM" conversation separate and honest rather than muddled by a tool that was never meant to be monitoring.

When to Consider This Package

Adopt when:

• The app runs Laravel 10–13.x and you control the PHP runtime — self-hosted, Docker, VPS, or a platform that permits enabling extensions. XHProf (or tideways_xhprof) is a hard dependency; verify it's loaded in both the web and CLI SAPIs before committing, because queue and command profiling is frequently the higher-value half.
• You have a named slow flow and an owner actively investigating it. This is a scalpel, not a monitoring system. It pays off when someone is going to read the output, not when it's installed "for later."
• You need queue job and Artisan command profiling, not just HTTP timing or query logs. Framework and serialization overhead is invisible to query-log tooling, and in many Laravel apps that's where the real cost lives.
• You need no external service, no vendor contract, no data egress — appropriate when a SaaS APM purchase isn't realistic this quarter for budget, legal, or procurement reasons.
• You're prepared to gate it by environment and skip routes. The v1.3.0 needle-based URL skipping makes health checks, webhooks, and admin panels trivial to exclude, and a sample rate caps both overhead and table growth.
• You can absorb small-project risk: ~235 stars, effectively zero dependents, maintenance driven largely by Laravel-major compatibility PRs. Acceptable for internal tooling if you pin the version, vendor it, and treat a fork as roughly a day of work.

Look elsewhere when:

• You need production observability — always-on tracing, real-user monitoring, historical trends, alerting, cross-service tracing. That's Datadog / New Relic / OpenTelemetry territory, and this package doesn't claim otherwise. Positioning it as "APM, but free" will not survive the first steering review.
• The extension can't be installed (shared hosting, locked managed runtime, extensions behind a support ticket). Fall back to Tideways or Blackfire, or a narrow DB::listen approach if the question is purely query-related.
• Your storage story is immature. Database storage is the default and creates a retention obligation; plan pruning or switch to disk before enabling it broadly in a high-traffic staging environment.
• You need trend analysis or release-over-release reporting as a standing deliverable. This is point-in-time inspection, not a time-series system.
• The organization already pays for an APM tool that supports staging code-level profiling. A second profiler in a different format buys little and adds a training curve.
• You can't resource the enable → profile → fix → retire loop. Shipping the middleware and never reading a profile is pure overhead plus migration surface.

How to Pitch It (Stakeholders)

One-line framing: a free, MIT-licensed Laravel package that turns "the app is slow" into a ranked, evidence-backed list of bottlenecks in about an hour of setup — scoped to development and staging, with no vendor contract and no production footprint.

For executives — this is a capacity-allocation decision, not a tooling purchase:

• What it buys us: we stop guessing which performance work matters. One session on our top three slow flows tells us whether to invest in queries, caching, or infrastructure — before we commit a sprint to any of them.
• What it costs: roughly an hour of one engineer's time, an approved PHP extension, and no license fee. That's the honest number; I won't promise APM savings we can't actually cancel.
• What it does not do: it isn't production monitoring and it won't page anyone. If we later need real-user monitoring or cross-service tracing, that's a separate, larger buy — and this pilot helps scope that RFP by showing which flows are worth monitoring continuously.
• The ask: approve a timeboxed pilot — staging only, two flows, one sprint, then a one-page readout covering bottlenecks found, fixes shipped, and measured before/after. Continue or drop based on that readout.

For engineering leaders — three concrete wins, one real risk:

• Wins: (1) request- and job-level call trees and flame graphs without anyone hand-writing instrumentation; (2) environment- and route-gated, so it stays out of production and off health checks; (3) callable from code, so performance assertions can live in CI rather than on a wiki.
• The risk we're accepting: a small open-source project with effectively no downstream dependents and maintenance tied to Laravel-major compatibility PRs. Mitigation is cheap — pin the version, vendor it, and treat a fork as a day of work if the maintainer goes quiet. Acceptable for internal, non-production tooling.
• Sequencing: pilot in staging → land one CI performance assertion on a business-critical endpoint → expand to queue jobs and commands, where the cost win usually is.

For engineers — what changes about your day:

• Flag a route or wrap a command and get a call tree of wall time, memory, and call counts — including framework overhead that query-log tools miss entirely.
• Setup is Composer plus published config and migrations plus xhprof.so enabled in both web and CLI php.ini. Verify the extension first; if it's missing, stop and pick another path rather than debugging a silent no-op a week later.
• Two operational notes worth writing into the README on day one: register the middleware early in the stack so wall-time attribution is accurate, and set a sample rate plus a pruning routine before pointing it at anything high-volume — otherwise the profiles table grows faster than anyone expects.
• Explicit anti-goal: don't enable this in production. It's a diagnostic tool with real overhead, and its value comes from deliberate, targeted use.