Laravel Profiler Laravel Package

Technical Evaluation

Positioning. jkocik/laravel-profiler is a development-time observability tool for Laravel: a middleware-driven collector set (request/response, DB queries, events, logs, views, session, timeline) with a bundled inspection UI. It is a DX/platform tool, not a runtime dependency of the product. It competes with Laravel Telescope (first-party, heavier) and barryvdh/laravel-debugbar (in-page toolbar). At 189 stars, MIT, and a single-maintainer signal, treat this as a trial-tier candidate, not a platform commit.

Architecture fit. Good shape for Laravel: service provider + publishable config + auto-discovery, collectors registered against framework events, pluggable storage (flat-file JSON by default, DB or custom driver), and a separate route for the UI. It is non-invasive—no domain code changes—but it is a cross-cutting concern inserted into the request lifecycle, so its blast radius is every request in any environment where it is enabled. It belongs in the "dev experience" layer only.

Integration feasibility. High for a conventional Laravel monolith: composer require --dev, publish config, register the profiler middleware, choose a storage driver, gate the UI route. A competent Laravel engineer can produce a working spike in half a day. Friction points: request-middleware designs give weak coverage of queue workers, scheduled commands, and artisan execution; environment gating and route protection are configuration responsibilities the package does not solve for you.

Technical risk.

Key questions to resolve in the spike.

1. What Laravel/PHP matrix does the latest tag actually declare, and when was it last released?
2. Is the UI route registered unconditionally, and can it be constrained by middleware, gate, or IP allowlist?
3. Is there a supported retention/pruning mechanism for file and DB storage?
4. Is there any redaction/masking configuration for captured request and session data?
5. Measured per-request overhead with all collectors enabled vs. a minimal set?
6. Does it support on-demand/sampled profiling (header or tag) rather than always-on?
7. Behavior when a collector or storage write throws—does it degrade the response?
8. CI matrix, test coverage, and issue-response cadence (bus-factor evidence)?
9. Confirmed compatibility with Octane/queue workers, and coexistence with Telescope if both are present?

Integration Approach

Stack fit. Standard Laravel application (verify 8–11 range against the specific tag), PHP 7.4/8.x, Composer, Docker-based local dev, existing CI. No infrastructure prerequisites beyond writable storage if the file driver is used.

Migration path. There is nothing to migrate—this is additive and dev-only. Sequence:

1. Spike branch. Install with a pinned version constraint in require-dev; confirm auto-discovery on the target Laravel version, or register the provider manually.
2. Publish and commit config. Keep config/profiler.php in VCS so behavior is reviewable and forkable.
3. Environment gate. Enable only when an explicit env flag is set (PROFILER_ENABLED=true) and APP_ENV is local/staging-dev. Never rely on the package's default alone.
4. Protect the UI. Wrap the profiler route in auth + authorization gate, plus an IP allowlist for shared staging.
5. Pick storage deliberately. File driver for single-node local; DB driver only on shared staging with a scheduled prune; avoid pointing it at the production database.
6. Document. One page in the onboarding runbook: how to enable, where profiles land, how to read the timeline, how to clear storage.

Compatibility checks. Composer constraints vs. the app's PHP version; conflicts with Telescope/Debugbar (both hook the same events—disable one); middleware signature changes across Laravel majors; route-name collisions with application routes.

Sequencing. Week 1: spike + the nine questions above answered in writing. Week 2: decision gate — Adopt (local-only), Adopt with conditions, or Fall back to Telescope. If adopted, add it to the team's service template and add a CI assertion that the profiler cannot be enabled in the production config. Exit criteria (drop it): no release in 12 months, a blocking incompatibility with the next Laravel major, or a security gap that cannot be closed by configuration.

Operational Impact

Maintenance. Low but non-zero. As a require-dev dependency it never ships to production, so patch urgency is limited; review quarterly and at every Laravel major upgrade. The real maintenance cost is the single-maintainer bus factor—budget for the possibility of vendoring a fork (MIT permits this) and keep the config in-repo so a fork is a drop-in. Audit transitive dependencies at install time; a dev tool should not quietly pull in a large tree.

Support. Community-only: GitHub issues, no SLA, no vendor escalation. Name an internal owner (platform/DX) as the escalation point and the person who triages upgrades.

Scaling. Three axes. (1) Request overhead: collectors add CPU and I/O to every instrumented request—prefer on-demand or sampled profiling over always-on, and keep the collector set minimal. (2) Storage: file profiles accumulate unbounded; add a prune job or a "clear" habit in the runbook. (3) Topology: file storage is node-local, so in a multi-replica staging environment profiles are scattered and lost on container rebuild—acceptable for local, awkward for shared staging. The DB driver solves distribution but writes to the app schema and adds per-request inserts.

Failure modes to design against. A collector exception surfacing as a broken request; disk exhaustion from stale profile files; sensitive data (tokens, session, PII in request bodies) visible through an under-protected UI route; route collision; a post-upgrade silent no-data state that gives false confidence during debugging; double instrumentation when Telescope is also installed.

Ramp-up. Low. A Laravel developer is productive in under an hour; add a 30-minute onboarding walkthrough covering the timeline, the query panel, and the enable/disable switch. Total cost of adoption: roughly one engineer-day for the spike and documentation, plus one to two hours per quarter for version review. That is cheap enough to justify a time-boxed pilot and expensive enough to require an explicit decision rather than an ad-hoc composer require by one developer.