README

Revolutionize Your Debugging Experience with PHP

Buggregator Trap

Trap is a package designed to enhance the debugging experience in conjunction with the Buggregator Server.
Trap includes:

A set of functions for direct interaction with any Buggregator server.
Extensions for Symfony VarDumper that become active immediately after installing Trap.
A minimized version of the Buggregator Server that does not require Docker and is intended solely for local use.

Table of content:

Installation
Overview
Usage
Contributing
License

Installation

To install Buggregator Trap in your PHP application, add the package as a dev dependency to your project using Composer:

composer require --dev buggregator/trap -W

And that's it. Trap is ready to go.

Phar

Sometimes your project may conflict with Trap's dependencies, or you might be interested in using only the local server (e.g., for analyzing local profiler files). In this case, consider installing Trap as a Phar (a self-contained PHP executable). Using wget:

wget https://github.com/buggregator/trap/releases/latest/download/trap.phar
chmod +x trap.phar
./trap.phar --version

Using Phive:

phive install buggregator/trap

Overview

Buggregator Trap provides a toolkit for use in your code. Firstly, just having Buggregator Trap in your package enhances the capabilities of Symfony Var-Dumper.

If you've already worked with google/protobuf, you probably know how unpleasant it can be. Now let's compare the dumps of protobuf-message: on the left (with trap) and on the right (without trap).

This simultaneously compact and informative output format of protobuf message will be just as compact and informative in the Buggregator Server interface. Now, working with protobuf is enjoyable.

Buggreagtor Trap includes a console application - a mini-server. The application is entirely written in PHP and does not require Docker to be installed in the system. It may seem like it's just the same as the symfony/var-dumper server, but it's not. Buggregator Trap boasts a much wider range of handlers ("traps") for debug messages:

Symfony var-dumper,
Monolog,
Sentry,
SMTP,
HTTP dumps,
Ray,
Any raw data

You can effortlessly visualize and analyze console information about various elements of your codebase.

Here's a sneak peek into the console output you can expect with Trap:

Additionally, you can manually set traps in the code. Use the trap() function, which works almost the same as Symfony's dump(), but configures the dumper to send dumps to the local server, unless other user settings are provided.

Also, the trap() has a lot of useful options:

// Limit the depth of the dumped structure
trap($veryDeepArray)->depth(3);

foreach ($veryLargeArray as $item) {
    // We don't need to dump more than 3 items
    trap($item)->times(3);
}

// Dump once if the condition is true
trap($animal)->once()->if($var instanceof Animal\Cat);

Tip

Feature in development: add the flag --ui to rise the web interface of the Buggregator Server without docker.

We care about the quality of our products' codebase and strive to provide the best user experience. Buggregator Trap has passed the Proof of Concept stage and is now an important part of the Buggregator ecosystem. We have big plans for the development of the entire ecosystem and we would be delighted if you join us on this journey.

Usage

After successfully installing Buggregator Trap, you can initiate the debugging process by using the following command:

vendor/bin/trap

This command will start the Trap server, ready to receive any debug messages. Once a debug message is trapped, you will see a convenient report about it right here in the terminal.

Then just call the trap() function in your code:

// dump the current stack trace
trap()->stackTrace();

// dump a variable with a depth limit
trap($var)->depth(4);

 // dump a named variables sequence
trap($var, foo: $far, bar: $bar);

// dump a variable and return it
$responder->respond(trap($response)->return());

Note: The trap() function configures $_SERVER['REMOTE_ADDR'] and $_SERVER['REMOTE_PORT'] automatically, if they are not set.

Also, there are a couple of shortcuts here:

tr(...) - equivalent to trap(...)->return()
td(...) - equivalent to trap(...); die;

If called without arguments, they will display a short stack trace, used memory, and time between shortcut calls.

function handle($input) {
    tr(); // Trace #0  -.---  3.42M

    $data = $this->prepareData($input);

    tr(); // Trace #1  0.015ms  6.58M

    $this->processor->process(tr(data: $data));

    td(); // exit with output: Trace #2  1.15ms  7.73M
}

Default port

Trap automatically recognizes the type of traffic. Therefore, there is no need to open separate ports for different protocols. By default, it operates on the same ports as the Buggregator Server: 9912, 9913, 1025, and 8000. However, if you wish to utilize a different port, you can easily make this adjustment using the -p option:

vendor/bin/trap -p9912 --ui=8000

Environment variables can also be used to set endpoints:

TRAP_TCP_PORTS - for TCP traffic: 9912,9913,1025,8000
TRAP_TCP_HOST - for the TCP host (default: 127.0.0.1)
TRAP_UI_PORT - for the web interface: 8080

Choosing Your Senders

Buggregator Trap provides a variety of "senders" that dictate where the dumps will be sent. Currently, the available sender options include:

console: This option displays dumps directly in the console.
server: With this choice, dumps are sent to a remote Buggregator server.
file: This allows for dumps to be stored in a file for future reference.

By default, the Trap server is set to display dumps in the console. However, you can easily select your preferred senders using the -s option.

For instance, to simultaneously use the console, file, and server senders, you would input:

vendor/bin/trap -s console -s file -s server

Contributing

We believe in the power of community-driven development. Here's how you can contribute:

Report Bugs: Encounter a glitch? Let us know on our issue tracker.
Feature Suggestions: Have ideas to improve the Buggregator Trap? Create a feature request!
Code Contributions: Submit a pull request to help us improve the Buggregator Trap codebase. You can find a list of issues labeled "help wanted" here.
Documentation: Help us improve our guides and tutorials for a smoother user experience.
Community Support: Join our Discord and help others get the most out of Buggregator.
Spread the Word: Share your experience with Buggregator on social media and encourage others to contribute.
Donate: Support our work by becoming a patron or making a one-time donation

Remember, every great developer was once a beginner. Contributing to open source projects is a step in your journey to becoming a better developer. So, don't hesitate to jump in and start contributing!

License

Buggregator Trap is open-sourced software licensed under the BSD-3 license.

buggregator / trap

Maintainers

Details