{"id":26452952,"url":"https://github.com/buggregator/trap","last_synced_at":"2025-05-15T19:06:49.847Z","repository":{"id":166620058,"uuid":"640186206","full_name":"buggregator/trap","owner":"buggregator","description":"A local debug server and utilities set for PHP projects","archived":false,"fork":false,"pushed_at":"2025-04-16T14:20:06.000Z","size":3890,"stargazers_count":172,"open_issues_count":34,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-12T14:00:44.443Z","etag":null,"topics":["buggregator","bugregator","cli","composer","composer-package","console","debug","dump","hacktoberfest","php","sentry","smtp"],"latest_commit_sha":null,"homepage":"https://buggregator.dev","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buggregator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"roxblnfk","custom":["https://boosty.to/roxblnfk"]}},"created_at":"2023-05-13T09:09:06.000Z","updated_at":"2025-05-07T17:27:40.000Z","dependencies_parsed_at":"2023-11-18T20:30:49.199Z","dependency_job_id":"4ebbf989-26a3-4f5d-843e-502c0cd546ca","html_url":"https://github.com/buggregator/trap","commit_stats":null,"previous_names":["buggregator/trap"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buggregator%2Ftrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buggregator%2Ftrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buggregator%2Ftrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buggregator%2Ftrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buggregator","download_url":"https://codeload.github.com/buggregator/trap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254404357,"owners_count":22065641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buggregator","bugregator","cli","composer","composer-package","console","debug","dump","hacktoberfest","php","sentry","smtp"],"created_at":"2025-03-18T18:40:20.157Z","updated_at":"2025-05-15T19:06:49.815Z","avatar_url":"https://github.com/buggregator.png","language":"PHP","readme":"\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"logo\"\n         src=\"https://github.com/buggregator/trap/blob/master/resources/payloads/logo.png?raw=true\"\n         style=\"width: 3in; display: block\"\n    /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003eRevolutionize Your Debugging Experience with PHP\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eBuggregator Trap\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Twitter](https://img.shields.io/badge/-Follow-black?style=flat-square\u0026logo=X)](https://twitter.com/buggregator)\n[![Discord](https://img.shields.io/static/v1?style=flat-square\u0026label=Join\u0026message=Discord\u0026logo=Discord\u0026color=%235865F2)](https://discord.gg/qF3HpXhMEP)\n[![Support](https://img.shields.io/static/v1?style=flat-square\u0026label=Support\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe0086)](https://patreon.com/roxblnfk)\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n**Trap** is a package designed to enhance the debugging experience in conjunction with the Buggregator Server.  \nTrap includes:\n\n- A set of functions for direct interaction with any Buggregator server.\n- Extensions for Symfony VarDumper that become active immediately after installing Trap.\n- A minimized version of the [Buggregator Server](https://github.com/buggregator/server) that does not require Docker\n  and is intended solely for local use.\n- Use PHPStorm? Consider using Trap with the [Buggregator Plugin](https://github.com/buggregator/phpstorm-plugin) for a seamless debugging experience.\n\n**Table of content:**\n\n- [Installation](#installation)\n- [Overview](#overview)\n- [Usage](#usage)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nTo install Buggregator Trap in your PHP application, add the package as a dev dependency\nto your project using Composer:\n\n```bash\ncomposer require --dev buggregator/trap -W\n```\n\n[![PHP](https://img.shields.io/packagist/php-v/buggregator/trap.svg?style=flat-square\u0026logo=php)](https://packagist.org/packages/buggregator/trap)\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/buggregator/trap.svg?style=flat-square\u0026logo=packagist)](https://packagist.org/packages/buggregator/trap)\n[![License](https://img.shields.io/packagist/l/buggregator/trap.svg?style=flat-square)](LICENSE.md)\n[![Total Downloads](https://img.shields.io/packagist/dt/buggregator/trap.svg?style=flat-square)](https://packagist.org/packages/buggregator/trap)\n\nAnd that's it. Trap is [ready to go](#usage).\n\n### Phar\n\nSometimes your project may conflict with Trap's dependencies, or you might be interested in using only the local\nserver (e.g., for analyzing local profiler files).\nIn this case, consider installing Trap as a Phar (a self-contained PHP executable).\nUsing wget:\n\n```bash\nwget https://github.com/buggregator/trap/releases/latest/download/trap.phar\nchmod +x trap.phar\n./trap.phar --version\n```\n\nUsing [Phive](https://phar.io/):\n\n```bash\nphive install buggregator/trap\n```\n\n## Overview\n\nBuggregator Trap provides a toolkit for use in your code. Firstly, just having Buggregator Trap in your\npackage enhances the capabilities of Symfony Var-Dumper.\n\nIf you've already worked with `google/protobuf`, you probably know how unpleasant it can be.\nNow let's compare the dumps of protobuf-message: on the left (with trap) and on the right (without trap).\n\n![trap-proto-diff](https://github.com/buggregator/trap/assets/4152481/30662429-809e-422a-83c6-61d7d2788b18)\n\nThis simultaneously compact and informative output format of protobuf message will be just as compact\nand informative in the Buggregator Server interface. Now, working with protobuf is enjoyable.\n\n---\n\nBuggreagtor Trap includes a console application - a mini-server.\nThe application is entirely written in PHP and does not require Docker to be installed in the system.\nIt may seem like it's just the same as the `symfony/var-dumper` server, but it's not.\nBuggregator Trap boasts a much wider range of handlers (\"traps\") for debug messages:\n\n- Symfony var-dumper,\n- Monolog,\n- Sentry,\n- SMTP,\n- HTTP dumps,\n- Ray,\n- Any raw data\n\nYou can effortlessly visualize and analyze console information about various elements of your codebase.\n\nHere's a sneak peek into the console output you can expect with Trap:\n\n| symfony/var-dumper (proto)                                                                             | Binary Data                                                                                             |\n|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|\n| ![var-dumper](https://github.com/buggregator/trap/assets/4152481/f4c855f5-87c4-4534-b72d-5b19d1aae0b0) | ![Binary Data](https://github.com/buggregator/trap/assets/4152481/cd8788ed-b10c-4b9a-b2e2-baa8912ea38d) |\n\n| SMTP Mail Trap                                                                                   | HTTP Dump                                                                                         |\n|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|\n| ![smtp](https://github.com/buggregator/trap/assets/4152481/b11c4a7f-072a-4e66-b11d-9bbd3177bfe2) | ![http-dump](https://github.com/buggregator/trap/assets/4152481/48201ce6-7756-4402-8954-76a27489b632) |\n\n---\n\nAdditionally, you can manually set traps in the code. Use the `trap()` function,\nwhich works almost the same as Symfony's `dump()`, but configures the dumper to send dumps to the local server,\nunless other user settings are provided.\n\nAlso, the `trap()` has a lot of useful options:\n\n```php\n// Limit the depth of the dumped structure\ntrap($veryDeepArray)-\u003edepth(3);\n\nforeach ($veryLargeArray as $item) {\n    // We don't need to dump more than 3 items\n    trap($item)-\u003etimes(3);\n}\n\n// Dump once if the condition is true\ntrap($animal)-\u003eonce()-\u003eif($var instanceof Animal\\Cat);\n```\n\n---\n\n\u003e [!TIP]\n\u003e Feature in development:\n\u003e add the flag `--ui` to rise the web interface of the Buggregator Server without docker.\n![trap-ui](https://github.com/buggregator/trap/assets/4152481/1ccc2c85-2f81-4b62-8ae7-49ee76380674)\n---\n\nWe care about the quality of our products' codebase and strive to provide the best user experience.\nBuggregator Trap has passed the Proof of Concept stage and is now an important part of the Buggregator ecosystem.\nWe have big plans for the development of the entire ecosystem and we would be delighted if you join us on this journey.\n\n## Usage\n\nAfter successfully [installing](#installation) Buggregator Trap, you can initiate the debugging process by using the following command:\n\n```bash\nvendor/bin/trap\n```\n\nThis 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.\n\nThen just call the `trap()` function in your code:\n\n```php\n// dump the current stack trace\ntrap()-\u003estackTrace();\n\n// dump a variable with a depth limit\ntrap($var)-\u003edepth(4);\n\n // dump a named variables sequence\ntrap($var, foo: $far, bar: $bar);\n\n// dump a variable and return it\n$responder-\u003erespond(trap($response)-\u003ereturn()); \n```\n\n\u003e **Note**:\n\u003e The `trap()` function configures `$_SERVER['REMOTE_ADDR']` and `$_SERVER['REMOTE_PORT']` automatically,\n\u003e if they are not set.\n\nAlso, there are a couple of shortcuts here:\n\n- `tr(...)` - equivalent to `trap(...)-\u003ereturn()`\n- `td(...)` - equivalent to `trap(...); die;`\n\nIf called without arguments, they will display a short stack trace, used memory, and time between shortcut calls.\n\n```php\nfunction handle($input) {\n    tr(); // Trace #0  -.---  3.42M\n\n    $data = $this-\u003eprepareData($input);\n\n    tr(); // Trace #1  0.015ms  6.58M\n\n    $this-\u003eprocessor-\u003eprocess(tr(data: $data));\n\n    td(); // exit with output: Trace #2  1.15ms  7.73M\n}\n```\n\n### Default port\n\nTrap automatically recognizes the type of traffic.\nTherefore, there is no need to open separate ports for different protocols.\nBy default, it operates on the same ports as the Buggregator Server: `9912`, `9913`, `1025`, and `8000`.\nHowever, if you wish to utilize a different port, you can easily make this adjustment using the `-p` option:\n\n```bash\nvendor/bin/trap -p9912 --ui=8000\n```\n\nEnvironment variables can also be used to set endpoints:\n\n- `TRAP_TCP_PORTS` - for TCP traffic: `9912,9913,1025,8000`\n- `TRAP_TCP_HOST` - for the TCP host (default: `127.0.0.1`)\n- `TRAP_UI_PORT` - for the web interface: `8080`\n\n### Choosing Your Senders\n\nBuggregator Trap provides a variety of \"senders\" that dictate where the dumps will be sent. Currently, the available\nsender options include:\n\n- `console`: Shows dumps directly in the console.\n- `server`: Sends dumps to a remote Buggregator server.\n- `file`: Saves dumps in a file for later use.\n- `mail-to-file`: Creates a folder for each recipient and saves each message as a JSON file. Useful for testing mails.\nIf you send a mail `To: foo@example.com, bar@example2.org`, the following folders will be created:\n  - `runtime/mail/foo@example.com`\n  - `runtime/mail/bar@example2.org`\n\nBy default, the Trap server is set to display dumps in the console. However, you can easily select your preferred\nsenders using the `-s` option.\n\nFor instance, to simultaneously use the console and file senders, you would input:\n\n```bash\nvendor/bin/trap -sconsole -sfile\n```\n\n## Contributing\n\nWe believe in the power of community-driven development. Here's how you can contribute:\n\n- Share your experience:  \n  - If you find a bug or have a feature request, please [create an issue](https://github.com/buggregator/trap/issues).\n  - Help others by answering questions on [Discord](https://discord.gg/qF3HpXhMEP) or asking your own.\n  - Share the love and tell others about Buggregator.\n- Write code:  \n  - If you want to fix a bug or add a feature, let us know in the issue tracker.\n    [There are issues](https://github.com/buggregator/trap/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) labeled \"help wanted\" that are a good place to start.\n  - Have good documentation writing skills? We'd love your help improving our [docs](https://github.com/buggregator/docs/tree/master/docs).\n- Sponsor us:  \n  - If you use Buggregator in a commercial setting, consider [becoming a sponsor](https://patreon.com/roxblnfk) to help us maintain and improve the project.\n  - You also can promote a specific feature or bug fix.\n    We mark sponsored tasks with the honorary label [`SPONSORED`](https://github.com/buggregator/trap/issues?q=label%3ASPONSORED).\n\n## License\n\nBuggregator Trap is open-sourced software licensed under the BSD-3 license.\n\n\u003c!--\n\n[![Contributors](https://contrib.rocks/image?repo=buggregator/trap)](https://github.com/buggregator/trap/graphs/contributors)\n\nQuality badges:\n\n[![Tests Status](https://img.shields.io/github/actions/workflow/status/buggregator/trap/testing.yml?label=tests\u0026style=flat-square)](https://github.com/buggregator/trap/actions/workflows/testing.yml?query=workflow%3Atesting%3Amaster)\n[![Dependency status](https://php.package.health/packages/buggregator/trap/dev-master/status.svg)](https://php.package.health/packages/buggregator/trap/dev-master)\n\n# (tests coverage)\n# (types coverage)\n# (psalm level)\n# (static analysis)\n# (mutation)\n# (scrutinizer score)\n# (code style)\n--\u003e\n","funding_links":["https://patreon.com/roxblnfk","https://boosty.to/roxblnfk"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuggregator%2Ftrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuggregator%2Ftrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuggregator%2Ftrap/lists"}