Performance Laravel Package

Technical Evaluation

Architecture fit

• Single-purpose, in-process instrumentation package: a Laravel service provider + facade + publishable config, with no external service, no database schema, no queue worker, and no daemon. That is the lowest possible integration footprint and fits cleanly as a require-dev dependency in a conventional Laravel application.
• Scope is deliberately narrow: elapsed time, peak memory, and DB query count per HTTP request, per Artisan command, and per plain CLI script. It is a point-in-time diagnostic snapshot, not an APM, not a tracing system, and not a continuous profiler. Position it accordingly.
• Complements rather than replaces Laravel Debugbar, Telescope, Clockwork, or OpenTelemetry. Expect functional overlap with the first two on the DB-query dimension — that overlap must be managed, not ignored.
• The low "opportunity" score (1.61) alongside 520 stars reads as a mature, commoditized niche: high utility, low differentiation, strong incumbent alternatives. That argues for adopt-with-guardrails, not build and not standardize org-wide.

Integration feasibility

• Install path is a standard composer require with package auto-discovery, vendor:publish for config, and either middleware registration or direct facade calls. Realistic effort is measured in hours for a first working spike, not sprints.
• The cross-context capability (web, web console, CLI) is genuinely useful for a TPM: the same metric vocabulary can be applied to a slow endpoint and a slow nightly batch job without introducing two tools.
• Blocking unknowns are version support and collection mechanics, both cheap to verify in a half-day spike.

Technical risk

• Production data exposure (highest severity). Any tool that renders timings, memory, and executed SQL into a response is an information-disclosure vector if it is ever enabled outside local/debug environments. This must be enforced structurally — conditional provider registration or an env-gated config default — not by developer discipline.
• Unbounded query accumulation in long-lived processes. If query capture relies on Laravel's query log, memory grows with the number of queries per worker lifecycle. Under Octane/Swoole or queue workers this is a genuine leak class, not a theoretical one. Verify whether the listener is request-scoped and resets.
• Response injection fragility. Middleware that appends to the response body can break JSON/API consumers, conflict with CSP headers, and interact badly with other response-mutating middleware depending on ordering.
• Maintainer concentration. Small-author package with no commercial backing and no SLA. Apache-2.0 is permissive and fork-friendly, which materially de-risks this, but a named internal owner is still required.
• Silent no-op. A config enable flag that defaults to false gives false confidence — teams believe they are measuring when they are not.

Key questions for the spike

1. What are the exact composer.json constraints for laravel/framework and php? Does it support Laravel 11/12 and PHP 8.2–8.4?
2. How are DB queries captured — a global DB::listen registration, enableQueryLog(), or a scoped listener? Is state reset per request, and is it Octane-safe?
3. Is output emission gated by environment at the code level, or only by a config boolean a developer can flip?
4. Is the public API semver-stable, and is there a CI matrix and test suite to evidence it?
5. Does it register a listener that duplicates Debugbar/Telescope, causing double-counted queries and additive overhead?
6. What is the measured per-request overhead at p50/p99 on a representative endpoint?
7. Can measurement be scoped to specific route groups or commands rather than globally?
8. Is there a documented safe production posture (disabled by default, no output path) or is the tool implicitly dev-only by convention?

Verdict: Adopt as a developer-facing, environment-gated diagnostic. Do not deploy to production runtimes. Do not treat it as a substitute for production observability.

Integration Approach

Stack fit

• Target: Laravel 8+ on PHP 7.4–8.x, plus standalone Composer projects. Install as require-dev so it never ships in a production artifact; where a shared codebase needs it available in a staging image, gate the provider registration on app()->environment(['local','staging']) or config('app.debug') inside AppServiceProvider.
• Configure the package's own enable flag to false in the committed config file and flip it only via local .env. Two independent gates (provider registration + config flag) is the correct defense-in-depth posture for a tool that prints SQL.
• Keep Debugbar/Telescope installed. They answer different questions (Debugbar: interactive inspection; Telescope: request history; this package: portable, scriptable metric capture for CLI and batch). Accept the overlap on query counting rather than trying to remove one.

Migration path

• No schema changes, no data migration, no backfill. Adoption is strictly additive and fully reversible by removing a dev dependency and a config file.
• If Debugbar already covers the HTTP case, scope the initial rollout to the CLI/Artisan case, where Debugbar is weakest and this package's value is clearest. That avoids a tooling turf war and gives a crisp first win.

Compatibility

• Validate composer.json constraints against the actual composer.lock before committing. Version drift after a Laravel major upgrade is the most likely breakage point; add an upgrade-checklist item.
• Check middleware ordering against existing response mutators (CORS, CSP, compression, JSON envelopes). Measure overhead with and without Debugbar/Telescope active to isolate listener duplication.
• Confirm behavior on the JSON/API surface — if the response injector is HTML-oriented, explicitly exclude api/* route groups.

Sequencing

1. Spike (0.5 day): branch, require-dev, publish config, measure a known-slow endpoint and one Artisan command. Answer the eight key questions above.
2. Gate (0.5 day): implement environment-conditional provider registration; commit config with enable => false; verify the package is inert in a production-env container build.
3. Pilot (1 week): enable for 3–5 engineers in local only; cover one HTTP route group and one batch command. Collect overhead numbers and false-positive/false-negative feedback.
4. Codify (1 week): document the workflow, add a short "how to profile a slow command" runbook entry, and record the explicit non-goal (not a production monitoring tool).
5. Decide: if the team's need is production latency visibility, run a separate APM/OpenTelemetry evaluation. Do not stretch this package to cover that gap.

Operational Impact

Maintenance

• Low ongoing surface area: one dev dependency, one config file, no runtime infrastructure. Cost is dominated by version-compatibility checks at each Laravel/PHP upgrade, not by day-to-day care.
• Single-maintainer concentration is the principal maintenance risk. Mitigate with a pinned version constraint (avoid floating ^ ranges in the near term), a calendar reminder to review releases quarterly, and an acknowledged fallback: Apache-2.0 permits an internal fork if upstream goes dormant. The recent release date is a positive signal but not a guarantee of cadence.
• Assign a named owner (typically a senior backend engineer) for upgrade compatibility. Unowned dev tooling rots silently.

Support

• Community-only support via GitHub issues; no vendor SLA, no security advisory process to rely on. Escalation path is: workaround → pin/rollback → internal fork.
• Because the tool is dev-only and gated, a support failure has no customer-facing blast radius. That containment is the single most important operational property of the integration and should be preserved deliberately.

Scaling

• Production scaling is not applicable by design; the correct answer to "will this scale?" is "it will never run in production."
• The scaling risk is accidental: a debug config promoted through an environment, or a developer enabling it in a shared staging environment under load. Concretely, per-request query capture multiplies memory by query count across concurrent workers, and rendered output inflates every response payload. Enforce the gates in CI (a test asserting the provider is not registered when APP_ENV=production) rather than relying on review.

Failure modes

• Information disclosure: timings, memory, and executed SQL exposed to end users. Severity high, likelihood low-but-nonzero. Mitigation: environment-gated registration + CI assertion + config default false.
• Memory growth in long-lived workers: query log accumulation under Octane or queue workers. Mitigation: confirm request-scoped reset, or restrict to CLI and standard FPM only.
• Broken responses: malformed JSON or corrupted HTML from body injection, or CSP violations. Mitigation: exclude API route groups; verify middleware order.
• Silent no-op: measurement disabled by config, team trusts numbers that are not being collected. Mitigation: surface "performance capture disabled" explicitly in the runbook and, where feasible, fail loudly in local.
• Double instrumentation: overlapping query listeners with Debugbar/Telescope inflating both overhead and reported query counts. Mitigation: baseline overhead with each tool isolated.
• Upgrade breakage: provider or facade fails to resolve after a framework bump. Mitigation: version pin + upgrade checklist item.

Ramp-up

• Roughly 1–2 hours for a mid-level Laravel developer: the concepts (service provider, facade, config publish) are already standard, and the API is a handful of start/stop/get calls. No new mental model required.
• The real ramp-up cost is interpretive, not mechanical: teaching engineers to read elapsed time vs. peak memory vs. query count together, and to distinguish query count from query cost. Budget a short internal demo and one worked example (a slow endpoint and a slow command) rather than documentation alone.
• Expect 1–2 weeks from spike to team-wide habit; expect the tool to be used sporadically thereafter, which is appropriate for a diagnostic of this kind. Judge success by "time to diagnose a slow command dropped measurably," not by adoption breadth.