Skip to content

Commit 579baa3

Browse files
butschsterbutschster
committed
Update trap section
1 parent cac597e commit 579baa3

File tree

6 files changed

+510
-74
lines changed

6 files changed

+510
-74
lines changed

‎docs/.vitepress/config.mts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@ export default defineConfig({
3535
{
3636
text: 'Getting Started',
3737
link: '/trap/getting-started',
38+
},
39+
{
40+
text: 'Commands',
41+
link: '/trap/commands',
42+
},
43+
{
44+
text: 'Usage',
45+
link: '/trap/usage',
3846
}
3947
]
4048
},

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ The key feature of Buggregator is its ability to bring together debugging inform
1818
means you can see all your debugging data in one place, which makes fixing bugs a whole lot easier and faster. It's a
1919
great tool for any developer looking to streamline their debugging process without spending a lot of money.
2020

21-
If you don't have Docker or you need debug your local PHP application, you can
21+
If you don't have Docker or you need debug your local PHP application with **Zero Configuration** just
2222
use [Buggregator Trap](./trap/what-is-trap.md). It's a lightweight alternative to the full Buggregator server, designed
2323
for local debugging.
2424

‎docs/trap/commands.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Trap — Commands
2+
3+
## `run`
4+
5+
### Description
6+
7+
The `run` command starts the Trap server, which listens for debug information on specified ports and
8+
processes it using configured senders.
9+
10+
### Simple Example
11+
12+
```bash
13+
vendor/bin/trap run
14+
```
15+
16+
### Arguments and Options
17+
18+
| Option | Short | Description | Default |
19+
|------------|-------|---------------------------------------------------------|--------------------------|
20+
| `--port` | `-p` | Port(s) to listen on (can be specified multiple times) | `1025, 8000, 9912, 9913` |
21+
| `--sender` | `-s` | Sender type(s) to use (can be specified multiple times) | `console` |
22+
| `--ui` | - | Enable web UI (with optional port specification) | `false` |
23+
24+
### Port Configuration Details
25+
26+
By default, Trap runs on multiple ports simultaneously: `1025, 8000, 9912, 9913`. All ports listen for the same data,
27+
but this multi-port setup makes it compatible with various debugging tools that have their own default ports:
28+
29+
- Port `1025`: Default SMTP port for email testing
30+
- Port `8000`: Used for HTTP dumps
31+
- Port `9912`: Default port for Symfony VarDumper
32+
- Port `9913`: Default for Monolog socket handler
33+
34+
If you want to listen on just one specific port, you can specify it:
35+
36+
```bash
37+
vendor/bin/trap run -p 8000
38+
```
39+
40+
This will make Trap listen only on port `8000`.
41+
42+
### Examples
43+
44+
Start with default settings:
45+
46+
```bash
47+
vendor/bin/trap run
48+
```
49+
50+
Listen on specific ports:
51+
52+
```bash
53+
vendor/bin/trap run --port=8888
54+
# or
55+
vendor/bin/trap run -p 8888
56+
```
57+
58+
Listen on multiple ports:
59+
60+
```bash
61+
vendor/bin/trap run --port=8888 --port=9999
62+
# or
63+
vendor/bin/trap run -p 8888 -p 9999
64+
```
65+
66+
Enable the web UI on default port:
67+
68+
```bash
69+
vendor/bin/trap run --ui
70+
```
71+
72+
Use environment variables for configuration:
73+
74+
```bash
75+
TRAP_TCP_PORTS=8888,9999 TRAP_UI_PORT=8080 vendor/bin/trap run --ui
76+
```
77+
78+
### Available Senders
79+
80+
Trap supports multiple methods ("senders") for outputting the debug information, allowing you to choose where your debug
81+
dumps are sent:
82+
83+
- **Console**: Outputs dumps directly in the console.
84+
- **Server**: Sends dumps to a remote Buggregator server for centralized management and review.
85+
- **File**: Saves dumps to a file, useful for auditing or detailed offline analysis.
86+
87+
By default, dumps are displayed in the console. However, you can configure multiple senders simultaneously to suit your
88+
workflow and requirements. For example, to use the console, file, and server senders together:
89+
90+
| Sender | Description |
91+
|----------------|--------------------------------------------------|
92+
| `console` | Outputs debug information to the console |
93+
| `file` | Writes events to files in JSON format |
94+
| `file-body` | Writes event body content to separate files |
95+
| `mail-to-file` | Stores received emails to files |
96+
| `server` | Forwards events to a Buggregator server instance |
97+
98+
99+
```bash
100+
vendor/bin/trap run --sender=console --sender=file
101+
```
102+
103+
## `test`
104+
105+
### Description
106+
107+
The `test` command sends various types of test data to the Trap server to verify that it's working correctly. This
108+
includes XHProf data, var dumps, emails, Sentry reports, and binary data.
109+
110+
### Simple Example
111+
112+
```bash
113+
vendor/bin/trap test
114+
```
115+
116+
### Arguments and Options
117+
118+
The `test` command doesn't accept any arguments or options.
119+
120+
### Example
121+
122+
To send test data to a running Trap instance:
123+
124+
```bash
125+
# First, start the trap server in one terminal
126+
vendor/bin/trap run
127+
128+
# Then, in another terminal, run the test command
129+
vendor/bin/trap test
130+
```
131+
132+
This will:
133+
134+
1. Send XHProf profiling data
135+
2. Execute various `trap()` dumps
136+
3. Send test emails (both simple and multipart)
137+
4. Send Sentry store and envelope data
138+
5. Send binary data
139+
140+
---
141+
142+
## `joke`
143+
144+
### Description
145+
146+
The `joke` command prints a random joke using the trap framework. It's a fun addition that also demonstrates the trap
147+
functionality.
148+
149+
### Simple Example
150+
151+
```bash
152+
vendor/bin/trap joke
153+
```
154+
155+
### Arguments and Options
156+
157+
The `joke` command doesn't accept any arguments or options.
158+
159+
### Example
160+
161+
To display a random joke:
162+
163+
```bash
164+
vendor/bin/trap joke
165+
```
166+
167+
The joke output will be displayed using the same output mechanism as other trap messages, which can be a good way to
168+
verify that your trap setup is working correctly in a lightweight manner.
169+
170+
## Environment Variables
171+
172+
Trap can be configured using environment variables:
173+
174+
| Variable | Description | Default |
175+
|-----------------------------|--------------------------------------------|-------------------------------------|
176+
| `TRAP_TCP_PORTS` | Comma-separated list of ports to listen on | `1025,8000,9912,9913` |
177+
| `TRAP_TCP_HOST` | Host interface to bind to | `127.0.0.1` |
178+
| `TRAP_TCP_POLLING_INTERVAL` | Socket polling interval in microseconds | `1000` |
179+
| `TRAP_UI_PORT` | Web UI port | `8000` |
180+
| `TRAP_UI_HOST` | Web UI host interface | `127.0.0.1` |
181+
| `TRAP_MAIN_LOOP_INTERVAL` | Main loop interval in microseconds | `100` |
182+
| `TRAP_XHPROF_PATH` | Path to XHProf files | Read from PHP's `xhprof.output_dir` |
183+
| `TRAP_XHPROF_SORT` | XHProf edges sorting algorithm (0-3) | `3` |

‎docs/trap/getting-started.md

Lines changed: 48 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,82 @@
11
# Trap — Getting Started
22

3-
To use Trap into your project, simply add it as a development dependency via Composer:
3+
There are several ways to get started with Trap, depending on your needs and preferences.
44

5-
```bash
6-
composer require --dev buggregator/trap -W
7-
```
5+
## Standalone Binary (No Project Dependencies)
86

9-
After installation, you can start the debugging server using:
7+
Download and extract the pre-compiled binary for your platform. This method allows you to use Trap across multiple PHP
8+
projects without modifying their dependencies.
109

11-
```bash
12-
vendor/bin/trap
13-
```
10+
**Available for platforms:**
1411

15-
This command will start the Trap server, ready to receive any debug messages. Once a debug message is trapped, you will
16-
see a convenient report about it right here in the terminal or in the browser.
12+
- Linux (amd64, arm64)
13+
- macOS (amd64, arm64)
14+
- Windows (amd64)
1715

18-
## Usage
16+
> **Note:** Binaries can be found on release page https://github.com/buggregator/trap/releases
1917
20-
The Trap offers a flexible and straightforward way to capture and analyze debug information in your PHP applications.
18+
```bash
19+
# Download (example for Linux amd64)
20+
curl -L -o trap.tar.gz https://github.com/buggregator/trap/releases/latest/download/trap-1.13.13-linux-amd64.tar.gz
2121

22-
Below is a guide on how to use the `trap` function to send debug messages to the Trap server.
22+
# Extract the archive
23+
tar -xzf trap.tar.gz
24+
rm trap.tar.gz
2325

24-
#### Sending Debug Messages
26+
# Make executable
27+
chmod +x trap
2528

26-
To begin sending debug messages, you can utilize the `trap()` function in various ways to suit your debugging needs:
29+
# Run
30+
./trap
31+
```
2732

28-
```php
29-
// Dump the current stack trace
30-
trap()->stackTrace();
33+
This command will start the Trap server, ready to receive any debug messages. Once a debug message is trapped, you will
34+
see a convenient report about it right here in the terminal or in the browser.
3135

32-
// Dump a variable with a specific depth limit
33-
trap($var)->depth(4);
36+
## Composer Installation
3437

35-
// Dump a sequence of named variables
36-
trap($var, foo: $far, bar: $bar);
38+
To use Trap into your project, simply add it as a development dependency via Composer:
3739

38-
// Dump a variable and return it for further processing
39-
$responder->respond(trap($response)->return());
40+
```bash
41+
composer require --dev buggregator/trap -W
4042
```
4143

42-
> **Note:** When using `trap()`, it automatically configures `$_SERVER['REMOTE_ADDR']` and `$_SERVER['REMOTE_PORT']` if
43-
> they are not already set. This ensures that the debug information is accurately captured and displayed.
44-
45-
## Default port
46-
47-
By default, Trap operates on port `9912`. To change the default port, you can use the `-p` option when starting the
48-
server:
49-
50-
For example, to switch to port `8000`, you would use the following command:
44+
After installation, you can start the debugging server using:
5145

5246
```bash
53-
vendor/bin/trap -p 8000
47+
vendor/bin/trap
5448
```
5549

56-
This command sets the Trap server to run on port `8000`.
50+
Once Trap is running, you can start debugging with the `trap()` function:
5751

58-
### Choosing Your Senders
59-
60-
Trap supports multiple methods ("senders") for outputting the debug information, allowing you to choose where your debug
61-
dumps are sent:
52+
```php
53+
// Basic variable dump
54+
trap($user);
6255

63-
- **Console**: Outputs dumps directly in the console.
64-
- **Server**: Sends dumps to a remote Buggregator server for centralized management and review.
65-
- **File**: Saves dumps to a file, useful for auditing or detailed offline analysis.
56+
// Named variable dumps
57+
trap(id: $userId, email: $userEmail);
6658

67-
By default, dumps are displayed in the console. However, you can configure multiple senders simultaneously to suit your
68-
workflow and requirements. For example, to use the console, file, and server senders together:
59+
// Dump and continue using the value
60+
$response = trap($api->getResponse())->return();
6961

70-
```shell
71-
vendor/bin/trap -s console -s file -s server
62+
// Set dump depth for nested objects
63+
trap($complexObject)->depth(3);
7264
```
7365

74-
This setup ensures that you can view debug information in real-time, save it for later review, and also send it to a
75-
remote server for centralized monitoring. Using Trap enhances your ability to diagnose and resolve issues
76-
quickly and efficiently, making it a valuable addition to your development toolkit.
77-
7866
## User Interface
7967

80-
Trap is set to enhance its usability by introducing a convenient new feature that allows users to launch the web
81-
interface of the Buggregator Server directly. This feature is aimed at improving accessibility and simplifying the
82-
debugging process.
83-
84-
![trap-ui](https://github.com/buggregator/trap/assets/4152481/1ccc2c85-2f81-4b62-8ae7-49ee76380674)
85-
86-
By adding the `--ui` flag when starting the Trap server, you can automatically raise the web interface. This allows for
87-
a more intuitive and graphical interaction with your debug data.
68+
By adding the `--ui` flag when starting the Trap server, you can automatically open the web interface. This allows for a
69+
more intuitive and graphical interaction with your debug data.
8870

8971
```bash
72+
./trap --ui
73+
# or
9074
vendor/bin/trap --ui
9175
```
9276

93-
This command will start the Trap server with the web interface enabled, facilitating direct access to the server's
94-
dashboard through your web browser. This is particularly useful for developers who prefer a graphical interface over
95-
command line interactions, providing a seamless experience without the need for Docker or additional setup.
77+
And just open the URL in your browser: [http://127.0.0.1:8000](http://127.0.0.1:8000).
78+
79+
## What's Next?
80+
81+
- Read more about the `trap()` function in the [Usage](./usage.md) section.
82+
- Explore the [Commands](./commands.md) for additional functionality.

0 commit comments

Comments
 (0)