Buggregator docs

Appearance

Trap — Functions ​

Trap is not just a server; it's also a useful collection of functions that help you debug your PHP applications.

trap() ​

Description ​

The trap() function is designed to capture and send variable dumps to the server. It serves as the primary entry point for debugging PHP applications, allowing developers to inspect variables, trace execution flow, and analyze application state at runtime.

Note: When using trap(), it automatically configures $_SERVER['REMOTE_ADDR'] and $_SERVER['REMOTE_PORT'] if they are not already set. This ensures that the debug information is accurately captured and displayed.

Signature ​

php
function trap(mixed ...$values): TrapHandle

The function accepts any number of arguments (named or positional) and returns a TrapHandle instance that provides additional debugging capabilities through method chaining.

Usage Examples ​

1. Basic Variable Dumping ​

php
// Dump a simple variable
trap($user);

// Dump multiple variables
trap($request, $response, $config);

// Use named arguments for better clarity
trap(user: $user, request: $request, response: $response);

This sends the variables to the Buggregator server where they can be inspected in the dashboard.

2. Stack Trace Inspection ​

php
// Add stack trace to your dump to see the execution flow
trap()->stackTrace();

// Dump a variable along with the stack trace
trap($result)->stackTrace();

This adds the current stack trace to your dump, showing the execution path that led to this point in your code.

3. Limiting Dump Depth ​

php
// Limit the dump depth to 4 levels for deeply nested objects
trap($complexObject)->depth(4);

// Dump multiple objects with depth limit
trap(user: $user, order: $order)->depth(2);

This is useful for complex objects where you want to limit how deep the dump will go into nested structures.

4. Conditional Dumping ​

php
// Dump only if a condition is met
trap($response)->if($statusCode >= 400);

// Using a callable for complex conditions
trap($query)->if(fn() => $query->count() > 100);

This lets you add conditional logic to your dumps, only showing them when specific conditions are met.

5. Limiting Dump Frequency ​

php
// Dump only once at this location in code
trap($i)->once();

// Dump only 5 times at this location
trap($i)->times(5);

// Dump only 3 times with full stack consideration (useful in recursion)
trap($recursiveData)->times(3, true);

This helps when debugging loops or recursive functions by limiting how many times the dump is shown.

6. Getting Values Back ​

php
// Dump a value and return it immediately
$result = trap($data)->return();

// Chain operations without breaking the flow
$response = $service->process(trap($request)->return());

// Return a specific named value
$name = trap(first: $firstName, last: $lastName)->return('last');

This allows you to insert debugging in the middle of expressions without disrupting your code flow.

7. Adding Context ​

php
// Add execution context to help understand the dump
trap($phpCode)->context(language: 'php', filename: 'Controller.php');

// Add context using an array
trap($data)->context(['environment' => 'production', 'user_id' => 42]);

// Shorthand for code highlighting
trap($sqlQuery)->code('sql');

This adds metadata to your dumps to provide more context for debugging.

8. Combining Multiple Features ​

php
// Combine multiple debugging features
trap($user)
    ->depth(3)
    ->if($user->isAdmin())
    ->context(role: 'admin', permissions: $user->getPermissions())
    ->once();

This example uses multiple features together to create a targeted debugging setup.

9. Working with Protobuf Messages ​

php
// Dump Protobuf messages with improved readability
trap($protoMessage);

The trap function includes special handling for Protocol Buffers, making them easier to debug.

10. Checking Performance with Ticks ​

php
// First tick
tr();

// Some code to measure
doSomething();

// Second tick will show time elapsed since first tick
tr();

The tr() function (a short alias) can be used to measure performance between points in your code.

tr() ​

Description ​

The tr() function is a shorthand alias for trap()->return(). When called without arguments, it works as a performance ticker, measuring time and memory usage between calls.

Signature ​

php
function tr(mixed ...$values): mixed

Usage Examples ​

1. Performance Measurement ​

php
// Mark the starting point
tr();

// Execute the code to measure
$result = heavyComputation();

// Mark the endpoint and see elapsed time and memory usage
tr();

This shows time elapsed and memory usage between calls.

2. Quick Value Inspection ​

php
// Dump and return in one call
$user = tr($repository->findUser($id));

// Chain in expressions
return tr($response->withHeader('Content-Type', 'application/json'));

This lets you inspect values while keeping them in your execution flow.

td() ​

Description ​

The td() function combines trap() with PHP's die statement, allowing you to dump values and terminate script execution. It's useful for quickly halting execution after inspecting critical values.

Signature ​

php
function td(mixed ...$values): never

Usage Examples ​

1. Debug and Die ​

php
// Dump value and terminate execution
td($error);

// Dump multiple values before terminating
td($request, $exception, $context);

This dumps the values to Buggregator and immediately terminates script execution.

2. Emergency Debugging ​

php
// When you need to stop and check what's happening
if ($unexpectedCondition) {
    td(message: 'Unexpected condition', data: $data);
}

This is useful during development to quickly halt execution at critical points.

3. Performance Check and Die ​

php
// Start measuring
tr();

// Run code to analyze
$result = complexOperation();

// Check result and terminate
td($result);

This combines performance measurement with termination, useful for profiling.