Weave Code
Trap Laravel Package
buggregator/trap
Buggregator Trap enhances PHP debugging with instant Symfony VarDumper integrations, handy helper functions, and a lightweight local Buggregator server (no Docker). Connect to any Buggregator server and pair with the PhpStorm plugin for a smooth workflow.
A local debug server and utilities set for PHP projects
Frequently asked questions about Trap
- How does `trap()` differ from Laravel’s `dd()` or `dump()`? Can I use it as a direct replacement?
- Trap’s `trap()` function extends Laravel’s debugging workflow by sending dumps to a Buggregator server (local or remote) while preserving the same behavior as `dd()` or `dump()`. It’s a drop-in replacement but adds structured debugging via the Buggregator UI or PhpStorm plugin. For example, `trap($user)` works like `dd($user)` but also logs the output to your Buggregator server for later inspection.
- Will Buggregator Trap work with Laravel 10+ and PHP 8.2+? Are there breaking changes?
- Yes, Trap is fully compatible with Laravel 10+ and PHP 8.2+. The package leverages modern PHP features and Symfony VarDumper’s latest versions, with no breaking changes in recent updates. Always check the [release notes](https://github.com/buggregator/trap/releases) for minor version-specific adjustments, but core functionality remains stable.
- How do I disable Trap in production to avoid performance overhead or accidental debug leaks?
- Trap is designed as a dev-only package and can be fully disabled in production by setting the `TRAP_ENABLED=false` environment variable or removing the `--dev` dependency. It won’t leave artifacts like log files or SMTP traps if disabled, as all senders are environment-aware. For extra safety, wrap `trap()` calls in `if (app()->environment('local'))` checks.
- Can I use Trap alongside Laravel Debugbar or Sentry? Will they conflict?
- Trap complements both Laravel Debugbar and Sentry rather than replacing them. Debugbar’s UI remains intact, while Trap adds structured debugging data to Buggregator or Sentry error reports. To avoid conflicts, explicitly configure Trap’s senders (e.g., `-sconsole` for CLI, `-ssentry` for Sentry) and ensure Sentry’s Laravel package isn’t duplicating debug payloads.
- Does the local Buggregator server interfere with Laravel’s queue workers or HTTP tests in CI/CD?
- The local server runs on default ports (9912, 9913, etc.) and won’t interfere with Laravel’s queue workers or HTTP tests by default. For CI/CD, disable the server via `TRAP_SERVER=false` or configure custom ports/hosts using `vendor/bin/trap --host=0.0.0.0 --port=9914`. Trap’s senders (e.g., `-sfile`) can also be restricted to local environments only.
- How do I debug complex data like gRPC payloads or serialized objects with Trap?
- Trap excels at debugging binary data (e.g., gRPC payloads, Protobuf messages) by rendering them in human-readable formats via the Buggregator UI or PhpStorm plugin. Install the `google/protobuf` extension for full Protobuf support, or use `trap($payload, ['raw' => true])` for fallback raw dumps. This is especially useful for Laravel apps using `spatie/laravel-grpc` or custom serialized data.
- Is there a performance impact when using Trap in staging environments? How does it compare to `dd()`?
- Trap introduces minimal latency (~1–5ms per dump) due to its local server, but this is negligible for staging. Unlike `dd()`, which halts execution, Trap’s `trap()` continues script flow unless you use `trap($var, ['die' => true])`. For staging, disable the server (`TRAP_SERVER=false`) and use file senders (`-sfile`) for post-mortem analysis without runtime overhead.
- How do I integrate Trap with PestPHP for testing? Can I use `td()` or `tr()` in assertions?
- Trap integrates seamlessly with PestPHP. Use `td()` (dump-and-die) or `tr()` (trace) in test assertions to inspect variables or execution flow, just like `dd()` or `dump()`. For example, `test('user creation', function () { $user = User::create(...); td($user->toArray()); })` will dump the user data to Buggregator for debugging failed tests.
- What alternatives to Buggregator Trap exist for Laravel debugging? How does it compare to Ray or Laravel Debugbar?
- Alternatives include **Ray** (real-time debugging with a web UI) and **Laravel Debugbar** (browser-based debugging). Trap stands out by offering a **local Buggregator server** (no Docker), **Protobuf/gRPC support**, and **PhpStorm integration**, while Ray focuses on web-based inspection and Debugbar on browser-specific tools. Trap is ideal for CLI-heavy Laravel apps or teams using Buggregator’s ecosystem.
- How do I configure Trap to work with a remote Buggregator server instead of the local one?
- To connect to a remote Buggregator server, omit the local server flag and specify the remote endpoint when running Trap. For example, `vendor/bin/trap -sconsole -h remote-buggregator.example.com -p 9912`. Ensure your Laravel app’s firewall allows outbound connections to the remote server on port 9912. Trap will auto-detect the remote server and route all dumps there.
Weaver
How can I help you explore Laravel packages today?