Inspector Php Laravel Package

Product Decisions This Supports

• Instrument-before-optimize prioritization. A transaction/segment model (startTransaction, addSegment) turns vague roadmap items like "make checkout faster" into measurable targets: wrap the suspect block, get per-segment timing, and rank backlog items by real execution cost rather than intuition.
• Build vs. buy for observability. Tracing/instrumentation is commodity plumbing. This package makes "buy/adopt instrumentation" the default and redirects engineering budget to product code. The MIT license plus the TransportInterface escape hatch means we retain the option to swap the ingestion backend later without re-instrumenting the app — the strongest argument against building a bespoke tracer.
• Incident response and support-tier decisions. Segment-level data lets us answer "why is Plan X slower than Plan Y?" without guessing, and feeds error-budget/alerting conversations. registerGlobalHandler() (v3.16.7) gives unhandled-exception capture with a single call — a cheap reliability win for legacy endpoints that currently fail silently.
• Async/queue architecture investment. fork() scopes (v3.17.0) are the differentiator: they create independent segment stacks per concurrent task, so Fibers, ReactPHP, or pcntl_fork workers don't corrupt parent-child relationships. This directly de-risks a roadmap bet on queue workers or event-loop services — without it, tracing async work is often actively misleading.
• Onboarding and tooling standardization. The MCP/agentic integration lets coding assistants read the library's capabilities, which lowers ramp-up cost for contractors and junior engineers and reduces "how do I instrument this?" support load.
• Vendor-risk and exit planning. Custom transport is effectively an exit clause: we can point the same instrumentation at an internal collector or a future vendor. That converts a monitoring purchase into a reversible, low-switching-cost decision rather than a platform commitment.

When to Consider This Package

Reasonable fit when:

• The service in question is PHP/Laravel-only (or overwhelmingly so) and running PHP 8.1+ — a hard floor, so confirm Laravel/runtime versions first.
• We need time-to-first-trace measured in hours, not sprints: composer install, ingestion key, one middleware line, done.
• The workload is synchronous or concurrent (APIs, CLI jobs, queue workers) and we care about correct span nesting under concurrency.
• We want optionality on the backend — MIT client code plus a custom transport we can point anywhere.
• Tracing literacy already exists on the team, or we're willing to invest a short ramp-up in concepts like transactions and segments.

Look elsewhere when:

• Polyglot or cross-service distributed tracing is the actual requirement. Instrumenting only PHP gives a partial picture; standardize on OpenTelemetry instead.
• Scale is extreme (very high RPS) and we need mature sampling, retention controls, and cost modeling — evaluate a dedicated APM before committing.
• RUM, session replay, or front-end performance are in scope; this is backend execution monitoring only.
• Compliance or air-gap constraints rule out a hosted dashboard, and we are not prepared to build and operate our own ingestion backend around the custom transport.
• Ecosystem maturity is a gate. At 34 stars and zero dependents, the community proof is thin; treat this as a vendor-supported library, not a community standard. Acceptable if the vendor relationship and source availability are enough, not acceptable if we need a large hiring pool and third-party integrations.
• We need SLO/error-budget management or advanced alerting — pair with Prometheus/Grafana or use a dedicated platform.
• The team has no tracing maturity — start with Telescope/Debugbar and revisit.

How to Pitch It (Stakeholders)

For executives (CTO/VP Eng): This is a low-cost way to stop guessing about backend performance. We get production-grade tracing and error visibility on our Laravel services for the price of a composer dependency and an API key — no agents to operate, no platform migration. It is genuinely reversible: the client is MIT-licensed and supports a custom transport, so we can redirect the same instrumentation to another backend later without redoing the work. Recommendation: pilot on one high-traffic service with a clear success metric (for example, 20% faster mean time to diagnose a performance issue). If the pilot hits it, expand; if not, we've spent days, not a quarter.

For engineering leaders (tech leads/SREs): Three concrete problems it removes. First, async debugging: fork() scopes give interleaved Fibers and queue workers correct parent-child spans, which our current logging cannot do. Second, toil: addSegment() and global exception registration replace ad-hoc timing code and scattered try/catch logging. Third, exit risk: TransportInterface means we are not locked into the dashboard. Trade-offs to accept up front: PHP 8.1+ only, no cross-language tracing, and a small community footprint — so we own version pinning and keep the integration thin (wrap it behind our own facade so removing it is a one-file change). Next step: instrument one service, compare findings against current logs for two weeks, then decide.

For developers: Wrap anything suspicious in addSegment() and the dashboard tells you where the time went — no more microtime() archaeology. For queue and Fiber work, use fork() so concurrent tasks don't tangle the span tree. Setup is a composer require and an API key; the docs also expose an MCP endpoint so your editor assistant understands the API without you reading the source. Try it locally on a slow endpoint this week and tell us whether it found something our logs missed.