Trap Laravel Package

Product Decisions This Supports

• Developer-experience investment (build vs. buy). Trap replaces a DIY "dump server + Docker compose + mail catcher" stack with a single dev dependency. The PM decision is whether debugging visibility is worth ~one afternoon of setup vs. the recurring tax of engineers re-inventing it per project. Trap is the buy option.
• Standardizing the debug toolchain. Because it works as a drop-in extension to Symfony VarDumper and ingests Monolog, Sentry, SMTP, HTTP dumps, Ray, and raw payloads on one port, it reduces tool sprawl. Roadmap implication: pick Trap or Ray-plus-log-tailing-plus-MailHog, not all four.
• Onboarding and time-to-first-diagnosis. composer require --dev then vendor/bin/trap means a new engineer can inspect payloads in minutes. This is a direct lever on ramp-up time for Laravel/Symfony teams.
• Feature work that needs local mail verification. The mail-to-file sender (per-recipient JSON folders) makes transactional-email work — password resets, receipts, multi-recipient notifications — testable without a real inbox. This supports scoping email-dependent features earlier in a roadmap.
• Debugging file-upload and multi-part HTTP flows. As of 1.18.0, uploaded files on an HTTP frame are correctly restored from their string form and each body in a batch is persisted to its own file. File-upload features (documents, CSVs, images, attachments) are now inspectable locally rather than requiring a staging round-trip.
• Protobuf/gRPC or binary-heavy surfaces. The compressed, readable protobuf rendering is a genuine workflow unlock for teams touching google/protobuf; it shortens debugging cycles on API-contract work.
• Docker-free local environment strategy. For teams standardizing on lighter local dev (native PHP, Sail-free, CI-friendly), Trap's embedded PHP mini-server removes a Docker dependency from the debugging loop.
• Test/QA tooling for backend behavior. Multiple senders (console, server, file, mail-to-file) let you choose persistence-per-environment, which is useful for reproducing bug reports rather than asking "what did your dump say?" Since 1.18.0, trap run reports startup errors and exits non-zero, which makes it usable as a gate in CI scripts rather than a silently-failing step.
• Explicit non-goal: production observability. Trap is a dev dependency with no auth, retention, or transport guarantees. Do not let it appear on a roadmap as an observability or incident-response item; that decision belongs to Sentry/OpenTelemetry-class tooling (which Trap can receive from, not replace).

When to Consider This Package

Consider it when:

• The stack is PHP 8.2+ (this is now a hard floor as of 1.18.0) and the team already uses dump()/VarDumper, Monolog, or Ray — Trap upgrades existing habits rather than replacing them. Teams still on PHP 8.1 must either stay on 1.17.x or defer adoption; treat the 8.2 requirement as a cost item if it forces a runtime upgrade ahead of your platform schedule.
• You want one local endpoint for multiple protocols (9912/9913/1025/8000 by default) instead of juggling separate dump-server, mail-catcher, and webhook tools.
• Docker is unavailable, slow, or politically undesirable on developer machines or CI runners.
• Dependency conflicts are a real risk — the PHAR/Dload install path lets you keep the project's Composer graph clean.
• You need scoped dump ergonomics (depth(), times(), once(), if(), stackTrace(), tr()/td()) to keep noisy debugging sessions readable. Timing deltas now report correct minutes for long-running requests, so tr() is trustworthy on slow endpoints and queue workers.
• Your team lives in PHPStorm — the companion Buggregator plugin is a coherent, supported pairing.
• You want Sentry-envelope inspection locally. This path has received sustained bug-fixing (attachment handling, envelope parsing after fixed-length items, events without an sdk key), so it is materially more dependable than at the prior review — but see the maturity caveat below.

Look elsewhere, or defer, when:

• The stack is not PHP, the project cannot move to PHP 8.2+, or the team has already standardized on a competing debug aggregator with entrenched workflows (migration cost exceeds benefit).
• You need production-grade tracing, alerting, retention, or multi-tenant access control. Trap is localhost-oriented by default; treat exposing its ports beyond 127.0.0.1 as a security decision, not a config tweak.
• You require vendor SLAs, a deprecation policy, or a formal security-response commitment. Changelogs here are largely auto-generated compare links, and community signals (stars, listed dependents) are modest — this is a healthy single-maintainer-centric OSS project, not an enterprise-supported product.
• You need the web UI in a supported, documented form. --ui is described in the README as a feature in development; do not build demo or training workflows that depend on it.
• Your team's debugging value comes from shared/remote collaboration rather than local inspection — that pulls you toward the hosted Buggregator server, a different (and distinct) adoption decision.

Adoption hygiene if you proceed: pin the version (note the 1.17 → 1.18 PHP 8.2 floor when pinning), install with --dev (be aware -W loosens root constraint resolution during install), keep default loopback hosts, and verify the phar release path if you intend to use it in CI. The density of correctness fixes in the 1.15 → 1.18 window — Sentry envelopes, base64 body chunking, HTTP file restoration, exception types on malformed frames — is a good sign of active maintenance but also a signal that the ingestion edge cases are still being found; budget for periodic upgrades rather than a one-time install.

How to Pitch It (Stakeholders)

For executives — one paragraph. Buggregator Trap is a free (BSD-3), developer-only debugging tool for our PHP services. It removes friction from the most expensive part of engineering work — figuring out why something is wrong — by giving every developer a single local window into dumps, logs, HTTP payloads, outbound emails, and error reports, with no Docker and no infrastructure to run or pay for. It is a dev dependency: it ships to no customer, adds no runtime cost, and carries no hosting or licensing expense. The realistic upside is faster onboarding and less time lost to ad-hoc debugging setups; the risk is bounded because removal is a one-line Composer change. The one gate: the current release line requires PHP 8.2+, so confirm our runtime position before standardizing.

For engineering leads. Install is composer require --dev buggregator/trap; starting the server is vendor/bin/trap. 1.18.0 requires PHP 8.2 — check the floor against each service before rolling out, and hold PHP 8.1 projects on 1.17.x or upgrade deliberately. It enhances VarDumper automatically, so existing dump() habits improve with zero code changes, and trap()/tr()/td() add depth- and count-limiting that keeps large payloads readable. Choose senders per environment (-sconsole, -sfile, -smail-to-file) so local work stays ephemeral and CI can persist artifacts; trap run now exits non-zero on startup failure, so a broken capture step fails the build instead of being missed. If Composer conflicts arise, use the PHAR or Dload binary instead of touching the app's dependency graph.

For security and platform. Defaults bind to loopback; keep it that way. Never expose the trap ports on shared networks or long-lived CI hosts, treat captured dumps and mail spool files as sensitive developer data (they can contain credentials and PII — HTTP body and attachment capture make this more, not less, true), and exclude them from version control.

What we are explicitly not buying. No production observability, no retention or alerting, no support contract, and no reliance on the in-development web UI. If those become requirements, they are separate roadmap items — Trap stays in the developer's terminal.