Home

Awesome

<p align="center"> <img alt="logo" src="https://github.com/buggregator/trap/blob/master/resources/payloads/logo.png?raw=true" style="width: 3in; display: block" /> </p> <p align="center">Revolutionize Your Debugging Experience with PHP</p> <h1 align="center">Buggregator Trap</h1> <div align="center">

Twitter Discord Support

</div> <br />

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

Table of content:

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

PHP Latest Version on Packagist License Total Downloads

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).

trap-proto-diff

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:

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:

symfony/var-dumper (proto)Binary Data
var-dumperBinary Data
SMTP Mail TrapHTTP Dump
smtphttp-dump

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. trap-ui


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:

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:

Choosing Your Senders

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

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:

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.

<!-- [![Contributors](https://contrib.rocks/image?repo=buggregator/trap)](https://github.com/buggregator/trap/graphs/contributors) Quality badges: [![Tests Status](https://img.shields.io/github/actions/workflow/status/buggregator/trap/testing.yml?label=tests&style=flat-square)](https://github.com/buggregator/trap/actions/workflows/testing.yml?query=workflow%3Atesting%3Amaster) [![Dependency status](https://php.package.health/packages/buggregator/trap/dev-master/status.svg)](https://php.package.health/packages/buggregator/trap/dev-master) # (tests coverage) # (types coverage) # (psalm level) # (static analysis) # (mutation) # (scrutinizer score) # (code style) -->