# Buggregator

> Buggregator is a free, open-source debugging server for PHP applications. Debug everything — install nothing. One docker run gives you exceptions, dumps, emails, profiling, and logs in a single real-time UI. Runs beside your app, not inside it.

- Install: `docker run --pull always -p 127.0.0.1:8000:8000 -p 127.0.0.1:1025:1025 -p 127.0.0.1:9912:9912 ghcr.io/buggregator/server:latest`
- GitHub: https://github.com/buggregator/server
- Lightweight CLI alternative (no Docker): `composer require --dev buggregator/trap`
- JetBrains IDE plugin: https://plugins.jetbrains.com/plugin/26344-buggregator
- Supported integrations: Sentry SDK, Symfony VarDumper, Monolog, Spatie Ray, Inspector, SMTP, HTTP dumps, XHProf, SMS
- Works with: Laravel, Symfony, Spiral, WordPress, Yii, Drupal — and JS, Python, Ruby, Go via Sentry SDK

---

# Configuration — External Database

Buggregator typically uses [DoltDB](https://github.com/dolthub/dolt) by default, which is a MySQL-compatible server.
However, for those who need more flexibility or plan to scale up, Buggregator also supports external databases such as
PostgreSQL and MySQL for data storage.

This guide will walk you through how to set up and configure an external database with Buggregator.

> **Warning**: Buggregator cannot work with SQLite. SQLite’s architecture does not support non-blocking, asynchronous
> operations.

## PostgreSQL

Here’s how you can configure PostgreSQL:

> **Warning**: Buggregator doesn’t create the database; it only sets up the tables inside it.

```dotenv
PERSISTENCE_DRIVER=db # database or cycle are also supported as an alias for db

DB_DRIVER=pgsql
DB_DATABASE=buggregator
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USERNAME=homestead
DB_PASSWORD=secret
```

## MySQL

Provide the connection details specific to the type of database you are using.

> **Warning**: Buggregator doesn’t create the database; it only sets up the tables inside it.

```dotenv
PERSISTENCE_DRIVER=db # database or cycle are also supported as an alias for db

DB_DRIVER=mysql
DB_DATABASE=buggregator
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USERNAME=homestead
DB_PASSWORD=secret
```

## Migrations

Buggregator automatically runs migrations when it starts. However, if you encounter any issues with the automatic
migrations, or if they were not executed for some reason, you can run them manually:

1. **Connect to the container:**
   Depending on your setup, you might use Docker, Kubernetes, or any other container service.

   For example, if you are using Docker, you can use the following command:

   ```bash
    docker exec -it buggregator /bin/bash
   ```

   Replace `buggregator` with the name of your container.

   If you are using Kubernetes, you can use the following command:

   ```bash
    kubectl exec -it buggregator -- /bin/bash
    ```

   Replace `buggregator` with the name of your pod.


2. **Run the migration command:**
   Within the container, execute the following command to force the migrations:

   ```bash
   php app.php migrate --force
   ```

   This command forcefully runs the migrations regardless of the current state, ensuring that all necessary tables are
   properly set up in the database.

## Docker compose example

Here’s an example of a `docker-compose.yml` file that sets up a PostgreSQL database for Buggregator:

```yaml
version: '3.9'

services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    depends_on:
      buggregator-database:
        condition: service_healthy
    ports:
      - 127.0.0.1:8000:8000
    environment:
      PERSISTENCE_DRIVER: db
      DB_DRIVER: pgsql
      DB_DATABASE: buggregator
      DB_HOST: buggregator-database
      DB_PORT: 5432
      DB_USERNAME: root
      DB_PASSWORD: secret

  buggregator-database:
    image: postgres:latest
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready --username=buggregator --dbname=buggregator" ]
      interval: 3s
      timeout: 3s
      retries: 1
    environment:
      POSTGRES_DB: buggregator
      POSTGRES_USER: root
      POSTGRES_PASSWORD: secret
```

---

# HTTP Dumps — Request Inspection

Your app calls external APIs, sends webhooks, or receives callbacks — and you need to see exactly what goes over
the wire. Buggregator captures full HTTP requests: method, URI, headers, cookies, POST data, and uploaded files.
You get a ready-to-use cURL command for any captured request. No need to set up a separate service like
webhook.site — it's built into the same Buggregator where you already see your logs and exceptions.

![http dumps](https://github.com/buggregator/server/assets/773481/fc823390-b490-4bbb-a787-44471eca9fb6)

## Use cases

- **Webhook development** — build a webhook endpoint and see exactly what the other service sends you.
- **API debugging** — redirect outgoing HTTP calls to Buggregator to inspect request structure before hitting the real API.
- **Replay requests** — copy the generated cURL command and replay any captured request from your terminal.
- **All in one place** — HTTP requests alongside exceptions, logs, and dumps in the same dashboard.

## What you see in the UI

- **HTTP method** — GET, POST, PUT, DELETE, PATCH, etc. (color-coded).
- **Full URI** — complete request URL with path segments.
- **Query parameters** — parsed URL query parameters.
- **POST/form data** — submitted fields and values.
- **Headers** — all request headers.
- **Cookies** — cookies sent with the request.
- **Uploaded files** — attached files, available for download.
- **cURL command** — generated automatically for easy replay.

## Configuration

Send any HTTP request to Buggregator and mark it as a dump. Two ways:

### Using HTTP auth

Add `http-dump` to the URL username:

```bash
curl 'http://http-dump@127.0.0.1:8000/any/path?foo=bar'
```

### Using header

Add the `X-Buggregator-Event` header:

```bash
curl 'http://127.0.0.1:8000/any/path?foo=bar' \
  --header 'X-Buggregator-Event: http-dump'
```

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name (e.g., `buggregator`).

---

# Inspector — Application Monitoring

You want to see how long your requests take, where the bottlenecks are, and how much memory each transaction
consumes — but [Inspector.dev](https://inspector.dev/) is overkill for local development. Buggregator accepts
the same Inspector SDK protocol, so your transaction and performance data lands in the same UI where you
already see exceptions, logs, and dumps.

![inspector](https://github.com/buggregator/server/assets/773481/ab002ecf-e1dc-4433-90d4-0e42ff8c0ab3)

## Use cases

- **Local APM** — monitor request duration and memory usage without sending data to external services.
- **Debug slow requests** — use the timeline breakdown to see which parts of a request are slow.
- **All in one place** — transaction data next to exceptions, logs, and dumps from the same app.

## What you see in the UI

- **Transaction name** — the name of the monitored transaction.
- **Duration** — execution time in milliseconds.
- **Memory peak** — peak memory usage.
- **Result status** — success, error, etc.
- **Transaction type** — HTTP request, process, etc.
- **HTTP details** — method, URI, host (for HTTP transactions).
- **Timeline breakdown** — visual timeline of events within the transaction.

## Configuration

### Laravel

Install the SDK: [docs.inspector.dev/laravel](https://docs.inspector.dev/laravel)

```dotenv
INSPECTOR_URL=http://inspector@127.0.0.1:8000
INSPECTOR_API_KEY=test
INSPECTOR_INGESTION_KEY=1test
INSPECTOR_ENABLE=true
```

> In Docker Compose: `INSPECTOR_URL=http://inspector@buggregator:8000`

### Other PHP

Using `inspector-apm/inspector-php`:

```php
use Inspector\Inspector;
use Inspector\Configuration;

$configuration = new Configuration('YOUR_INGESTION_KEY');
$configuration->setUrl('http://inspector@127.0.0.1:8000');
$inspector = new Inspector($configuration);
```

Other language SDKs: [docs.inspector.dev](https://docs.inspector.dev/)

## Secret key validation

To restrict access, set a secret key on the server:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e INSPECTOR_SECRET_KEY=my-secret-key \
  ghcr.io/buggregator/server:latest
```

Then use the key as the ingestion key in your client:

**Laravel:**

```dotenv
INSPECTOR_INGESTION_KEY=my-secret-key
```

**PHP:**

```php
$configuration = new Configuration('my-secret-key');
$configuration->setUrl('http://inspector@127.0.0.1:8000');
```

---

# Configuration — Metrics

Buggregator collects metrics on how many events it receives. This feature lets you use tools like
Prometheus and Grafana to check on event trends, find issues, and set up alerts.

The metrics system keeps track of how many events Buggregator receives, sorted by their types:
sentry, monolog, var-dumper, ray, inspector, http-dump, profiler, and smtp. Webhook deliveries are also tracked.

### How It Works

1. **Event Counting:** Each time an event is received, it’s counted and sorted into its type.
2. **Metric Updating:** The system updates the metrics to show the latest counts for each event type.

## Prometheus Endpoint

Buggregator has a built-in Prometheus friendly endpoint that you can use to collect metrics. Metrics are available at
`2112` port inside the container. To access the metrics outside the container, you need to expose the port.

```bash
docker run --pull always \
  ... \
  -p 2112:2112 \
  ghcr.io/buggregator/server:latest
```

> **Note:** Read more about server configuration [here](../getting-started.md).

After starting the server, you can access the metrics at `http://<server_address>:2112` address.

## Metric Format

Here is what the metric format looks like:

```plaintext
# HELP events The total number of received events.
# TYPE events counter
events{type="sentry"} 10
events{type="smtp"} 1
```

Each line shows how many events of a specific type we have received.

## Grafana Integration

You can use these metrics to make dashboards in Grafana. This helps you see the data in a way that makes sense for you.
We will provide steps on how to connect Buggregator’s metrics to Grafana.

### Setting Up Grafana

1. **Add Prometheus as a Data Source:** First, connect Prometheus (which has your Buggregator metrics) to Grafana.
2. **Create Dashboards:** Next, create dashboards in Grafana to show the metrics. You can make graphs and charts that
   help you understand the event trends.

---

# Monolog — Logs

Your app writes logs — but where do they go during development? A file you `tail -f`? Docker container output
you scroll through? With Buggregator, logs from all your services land in the same UI where you already see
exceptions, dumps, and emails. Filter by level, see structured context, click on source locations — all without
setting up Elasticsearch or a separate logging stack.

![monolog](https://github.com/buggregator/server/assets/773481/21919110-fd4d-490d-a78e-41242d329885)

## Use cases

- **Structured log viewer** — see context and extra fields as formatted JSON, not a raw string in a terminal.
- **Multi-service logging** — collect logs from all containers in one place.
- **Debug long-running apps** — workers, daemons, and queue consumers write logs that are easy to miss in stdout. Buggregator catches them all.
- **All in one place** — correlate logs with exceptions and dumps from the same request flow.

## What you see in the UI

- **Channel** — the logger channel (`app`, `security`, `database`, etc.).
- **Message** — the log message.
- **Severity level** — all PSR-3 levels: emergency, alert, critical, error, warning, notice, info, debug.
- **Timestamp** — when the log was recorded.
- **Context** — structured context data in JSON format.
- **Extra fields** — additional data from Monolog processors.
- **Source** — file, line, and function where the log was generated.

## Configuration

Buggregator receives logs via Monolog's `SocketHandler` on port **9913**. The formatter **must** be `JsonFormatter`.

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name (e.g., `buggregator:9913`).

### Laravel

```php
// config/logging.php
return [
    // ...
    'channels' => [
        // ...
        'socket' => [
            'driver' => 'monolog',
            'level' => env('LOG_LEVEL', 'debug'),
            'handler' => \Monolog\Handler\SocketHandler::class,
            'formatter' => \Monolog\Formatter\JsonFormatter::class,
            'handler_with' => [
                'connectionString' => env('LOG_SOCKET_URL', '127.0.0.1:9913'),
            ],
        ],
    ],
];
```

```dotenv
LOG_CHANNEL=socket
LOG_SOCKET_URL=127.0.0.1:9913
```

### Spiral Framework

```php
<?php

declare(strict_types=1);

namespace App\Bootloader;

use Monolog\Formatter\JsonFormatter;
use Monolog\Handler\SocketHandler;
use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Boot\EnvironmentInterface;
use Spiral\Monolog\Bootloader\MonologBootloader;

class LoggingBootloader extends Bootloader
{
    public function init(MonologBootloader $monolog, EnvironmentInterface $env): void
    {
        $handler = new SocketHandler($env->get('MONOLOG_SOCKET_HOST'), chunkSize: 10);
        $handler->setFormatter(new JsonFormatter(JsonFormatter::BATCH_MODE_NEWLINES));
        $monolog->addHandler('socket', $handler);
    }
}
```

```dotenv
MONOLOG_DEFAULT_CHANNEL=socket
MONOLOG_SOCKET_HOST=127.0.0.1:9913
```

### Symfony

```php
# config/packages/dev/monolog.php
<?php

namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Config\MonologConfig;

return static function (MonologConfig $monologConfig): void {
    $monologConfig
        ...
        ->handler('socket')
            ->level('debug')
            ->formatter('monolog.formatter.json')
            ->type('socket')
            ->connectionString(env('MONOLOG_SOCKET_HOST'));
};
```

```dotenv
MONOLOG_SOCKET_HOST=127.0.0.1:9913
```

> **Important:** The `monolog.formatter.json` formatter is required. Without it, Buggregator cannot parse the log records.

### Any PHP project

```bash
composer require monolog/monolog
```

```php
<?php

use Monolog\Logger;
use Monolog\Handler\SocketHandler;
use Monolog\Formatter\JsonFormatter;

$log = new Logger('buggregator');
$handler = new SocketHandler('127.0.0.1:9913');
$handler->setFormatter(new JsonFormatter());
$log->pushHandler($handler);

$log->warning('Foo');
$log->error('Bar');
```

---

# JetBrains IDE Plugin

You use PhpStorm (or another JetBrains IDE) and don't want to switch to a browser to check dumps and logs.
The Buggregator plugin embeds the full debug UI directly into your IDE — dumps, logs, exceptions, and profiling
data appear in a panel next to your code. All IDE shortcuts keep working. No context switching.

**Plugin repository:** https://github.com/buggregator/phpstorm-plugin

## How it works

The plugin launches [Buggregator Trap](/trap/what-is-trap) from your project's `vendor` directory using the PHP
interpreter configured in your IDE. Trap starts collecting debug data and the plugin displays it in two tabs:

- **Web UI** — the full interactive Buggregator interface in the IDE's built-in browser. Same UI as the standalone server.
- **Terminal** — text-based output for quick inspection.

Trap opens a web interface port (configurable in settings), which works with all standard clients — VarDumper,
Monolog, Sentry, Ray, and others.

> **Tip:** If you have the plugin running in multiple IDE windows with the same port, both Web UIs share the same
> Trap instance. A second Trap will wait until the port is free.

## Requirements

- [buggregator/trap](https://github.com/buggregator/trap) installed in your project (`composer require --dev buggregator/trap`)
- A PHP interpreter configured in your IDE settings

## Installation

### From JetBrains Marketplace (recommended)

Go to the [plugin page](https://plugins.jetbrains.com/plugin/26344-buggregator) and click **Install to ...**

### From IDE

**Settings** > **Plugins** > **Marketplace** > search for **"Buggregator"** > **Install**

### Manual

1. Download the `.jar` file from [GitHub Releases](https://github.com/buggregator/phpstorm-plugin/releases) or [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/26344-buggregator/versions).
2. **Settings** > **Plugins** > **⚙️** > **Install plugin from disk...** > select the `.jar` file.
3. Restart the IDE if prompted.

After installation, find the **Buggregator** button in the top right corner of the IDE window.

## Configuration

Open the plugin settings to customize:

- **PHP interpreter** — which PHP binary to use for running Trap.
- **Path to Trap** — defaults to `vendor/bin/trap`, change if needed.
- **Web UI port** — the port for the embedded web interface.

Click the **🌐** button on the toolbar to open the Web UI in your system browser instead of the IDE.

## Supported IDEs

The plugin works with all JetBrains IDEs that support PHP development:

- PhpStorm
- IntelliJ IDEA (with PHP plugin)
- WebStorm
- And other JetBrains products

---

# Configuration — Projects

Buggregator lets you use "projects" to help organize your data. Projects are useful for keeping events from
different teams, applications, or environments separate.

![image](https://github.com/user-attachments/assets/cde794f7-83fb-4708-9eef-713c6f8be7cc)

**Here’s why you might want to use projects:**

1. Projects help you keep data from different teams or parts of your app separate. This means it’s easier to find what
   you’re looking for and keep track of changes.
2. Teams won’t get mixed up with data that isn’t relevant to them, which makes their work faster and less confusing.
3. The sidebar displays a project selector dropdown, allowing you to quickly switch between projects and view only
   the events relevant to the selected project.

### Default Project

When you start the server, Buggregator automatically sets up a default project with key `default`. All your data goes
into this `default` project if a project key is not specified in the request.

## Docker Configuration

Currently, Buggregator does not have an admin interface for managing projects. Instead, you manage them through
configuration files within a Docker container.

**Here's how you can mount a volume containing webhook configurations:**

```bash
docker run --pull always \
  -v /path/to/projects:/app/runtime/configs \
  ghcr.io/buggregator/server:latest
```

or using `docker-compose`:

```yaml
buggregator-server:
  ...
  volumes:
    - /path/to/projects:/app/runtime/configs
```

## Configuring a Project

Place each project configuration in a YAML file within the `runtime/configs` directory. Each configuration file should
contain one project setup.

Here’s what a typical webhook configuration looks like in a YAML file `dev.project.yaml`:

```yaml
project:
  key: dev
  name: Dev environment
```

> **Note:** The project configuration file name should have the following pattern: `<name>.project.yaml`
> or `<name>.project.yml`.

## Sentry Configuration

To use Sentry with your project, format your DSN like this:

```dotenv
SENTRY_DSN=http://<secret_key>@127.0.0.1:8000/<project_key>
```

> **Note:** Read more about Sentry configuration [here](/config/sentry.html).

## Inspector Configuration

To use Inspector with your project, format your DSN like this:

```dotenv
INSPECTOR_URL=http://inspector:<project_key>@127.0.0.1:8000
INSPECTOR_API_KEY=<secret_key>
```

> **Note:** Read more about Inspector configuration [here](/config/inspector.html).

## Xhprof Profiler Configuration

To set up the Profiler, use this:

```dotenv
PROFILER_ENDPOINT=http://profiler:<project_key>@127.0.0.1:8000
```

> **Note:** Read more about Xhprof Profiler configuration [here](/config/xhprof.html).

## Ray Configuration

For Ray, use these settings:

```dotenv
RAY_HOST=ray:<project_key>@127.0.0.1
RAY_PORT=8082
```

## VarDumper Configuration

At this moment, VarDumper does not support projects.

## Monolog Configuration

At this moment, Monolog does not support projects.

---

# Ray — Debug Tool

[Ray](https://myray.app/) by Spatie is a popular debug tool, especially in the Laravel ecosystem. Buggregator is
a free, self-hosted alternative — you get the same `ray()` calls, but the data lands in Buggregator alongside
your exceptions, logs, emails, and profiling. One place for everything.

![ray](https://github.com/buggregator/server/assets/773481/168b27f7-75b1-4837-b0a1-37146d5b8b52)

## Use cases

- **Free Ray alternative** — no license needed. Same `ray()` function, same workflow.
- **Multi-language debugging** — Ray has SDKs for PHP, JavaScript, Ruby, Go, and Bash. All output goes to Buggregator.
- **Laravel debugging** — dump Eloquent models, SQL queries, jobs, mail, events, and more with type-specific rendering.
- **All debug data in one UI** — don't switch between Ray app, Sentry, log files, and Mailhog. It's all in Buggregator.

## Supported payload types

Buggregator renders 18 Ray payload types:

| Type | What it shows |
|---|---|
| **Log** | Text logging |
| **Custom** | Custom data dumps |
| **Caller** | Call origin (file, line, function) |
| **Carbon** | Carbon date/time objects |
| **Trace** | Full stack trace |
| **Exception** | Exception with stack trace |
| **Table** | Structured data as a table |
| **Measure** | Performance timing |
| **Query** | SQL query with bindings |
| **Eloquent** | Eloquent model data |
| **Application Log** | Application log entries |
| **View** | Template rendering info |
| **Event** | Application events |
| **Job** | Queue job details |
| **Lock** | Lock status |
| **Mailable** | Laravel Mail preview |
| **Notify** | Notification data |
| **Origin** | Call origin info |

Each payload shows its origin (file, line, function). Click file paths to open in your IDE.

## Configuration

### Laravel

Publish the Ray config:

```bash
php artisan ray:publish-config
```

Set env variables:

```dotenv
RAY_HOST=ray@127.0.0.1
RAY_PORT=8000
```

> In Docker Compose: `RAY_HOST=ray@buggregator`, `RAY_PORT=8000`.

### PHP (any framework)

Create a `ray.php` file in your project root:

```php
<?php

return [
    'enable' => true,
    'host' => 'ray@127.0.0.1',
    'port' => 8000,
    'remote_path' => null,
    'local_path' => null,
    'always_send_raw_values' => false,
];
```

### Other languages

- [JavaScript](https://myray.app/docs/javascript/vanilla-javascript/getting-started)
- [Ruby](https://myray.app/docs/other-languages/ruby/getting-started)
- [Go](https://myray.app/docs/other-languages/go/getting-started)
- [Bash](https://myray.app/docs/other-languages/bash/installation)

---

# Configuration — RoadRunner

The **Buggregator server** uses the **RoadRunner application server** to handle HTTP and TCP requests efficiently.
RoadRunner is a high-performance server written in Go, designed for PHP applications. In some cases, you might want to
customize its configuration to suit your needs, such as:

- Restricting **CORS rules** for security.
- Increasing **TCP buffer size** for better performance.
- Adjusting **logging settings** for different environments (e.g., development or production).

This guide explains how to configure the Buggregator server using RoadRunner's **environment variables**.

---

### Available ENV Variables

| **Variable Name**                | **Description**                                                                                           | **Default Value**  |
|----------------------------------|-----------------------------------------------------------------------------------------------------------|--------------------|
| `RR_LOG_MODE`                    | Logging mode: `development`, `production`, or `raw`.                                                      | `production`       |
| `RR_LOG_ENCODING`                | Log encoding format: `console` or `json`. Recommended `json` for production.                              | `json`             |
| `RR_LOG_LEVEL`                   | Global logging level: `panic`, `error`, `warn`, `info`, `debug`.                                          | `warn`             |
| `RR_LOG_HTTP_LEVEL`              | Logging level for HTTP plugin: `panic`, `error`, `warn`, `info`, `debug`.                                 | `warn`             |
| `RR_LOG_TCP_LEVEL`               | Logging level for TCP plugin: `panic`, `error`, `warn`, `info`, `debug`.                                  | `warn`             |
| `RR_LOG_CENTRIFUGE_LEVEL`        | Logging level for Centrifuge plugin: `panic`, `error`, `warn`, `info`, `debug`.                           | `warn`             |
| `RR_LOG_SERVER_LEVEL`            | Logging level for the server: `panic`, `error`, `warn`, `info`, `debug`.                                  | `warn`             |
| `RR_LOG_SERVICE_LEVEL`           | Logging level for services: `panic`, `error`, `warn`, `info`, `debug`.                                    | `warn`             |
| `RR_HTTP_ALLOWED_ORIGIN`         | Allowed origins for CORS. Typically set to specific domains or `*` for all.                               | `*`                |
| `RR_HTTP_ALLOWED_HEADERS`        | Allowed headers for CORS. Set `*` for all or specify headers.                                             | `*`                |
| `RR_HTTP_ALLOW_CREDENTIALS`      | Whether CORS credentials (cookies, authorization) are allowed.                                            | `true`             |
| `RR_HTTP_NUM_WORKERS`            | Number of workers in the HTTP pool. Determines concurrency for HTTP handling.                             | (Unset by default) |
| `RR_TCP_MONOLOG_ADDR`            | Address for the Monolog TCP server.                                                                       | `:9913`            |
| `RR_TCP_VAR_DUMPER_ADDR`         | Address for the Var-Dumper TCP server.                                                                    | `:9912`            |
| `RR_TCP_SMTP_ADDR`               | Address for the SMTP TCP server.                                                                          | `:1025`            |
| `RR_TCP_READ_BUF_SIZE`           | Buffer size for TCP data reading (in bytes). Higher values reduce `read` system calls for large payloads. | `50485760` (50MB)  |
| `RR_TCP_NUM_WORKERS`             | Number of workers in the TCP pool. Determines concurrency for TCP handling.                               | (Unset by default) |
| `RR_CENTRIFUGE_PROXY_ADDRESS`    | Proxy address for Centrifuge plugin.                                                                      | (Unset by default) |
| `RR_CENTRIFUGE_GRPC_API_ADDRESS` | gRPC API address for Centrifuge plugin.                                                                   | (Unset by default) |
| `RR_CENTRIFUGE_NUM_WORKERS`      | Number of workers in the Centrifuge poll.                                                                 | (Unset by default) |

---

### Example: Using ENV Variables in Docker Compose

To configure RoadRunner through environment variables in `docker-compose.yml`, use the following example:

```yaml
version: '3.9'

services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    environment:
      RR_LOG_MODE: json         # Set logging mode to JSON
      RR_HTTP_NUM_WORKERS: 4    # Configure the number of HTTP workers
      RR_TCP_READ_BUF_SIZE: 10485760 # Set TCP read buffer size to 10MB
      RR_HTTP_ALLOWED_ORIGIN: "https://example.com" # Restrict allowed CORS origins
```

### Example: Using ENV Variables with `docker run`

You can also pass environment variables directly when running a Docker container:

```bash
docker run --pull always \
  -e RR_LOG_MODE=json \            # Set logging mode to JSON
  -e RR_HTTP_NUM_WORKERS=4 \       # Configure the number of HTTP workers
  -e RR_TCP_READ_BUF_SIZE=10485760 \ # Set TCP read buffer size to 10MB
  -e RR_HTTP_ALLOWED_ORIGIN="https://example.com" \ # Restrict allowed CORS origins
  ghcr.io/buggregator/server:latest
```

---

# Sentry — Exceptions

You want to see exceptions with stack traces, breadcrumbs, and request context — but you don't want to deploy
a full Sentry instance just for local development. Buggregator accepts the same Sentry SDK protocol, so you
change one line in your config and get exception tracking alongside all your other debug data — logs, dumps,
emails, profiling — in a single UI.

No registration. No limits. No heavy infrastructure.

![sentry](https://github.com/buggregator/server/assets/773481/e979fda5-54c8-42cc-8224-a1c5d828569a)

## Use cases

- **Long-running apps** (RoadRunner, Swoole, queue workers) — exceptions don't show in the browser, but they show in Buggregator.
- **Microservices / Docker Compose** — collect exceptions from all services in one place instead of checking each container's logs.
- **Frontend + Backend** — catch JavaScript errors alongside PHP exceptions in the same dashboard.
- **Quick local debugging** — don't wait for errors to appear in a remote Sentry instance. See them instantly.

## What you see in the UI

- **Exception** — frame-by-frame stack trace with file paths, line numbers, and code context. Click to open in your IDE.
- **Breadcrumbs** — timeline of user actions and system events leading up to the error.
- **Request** — HTTP method, URI, headers, cookies, POST data.
- **Device** — browser, OS, device type.
- **App** — application name, version, build.
- **Tags & Extra** — custom key-value data attached to the event.
- **Modules** — loaded packages with versions.

## Configuration

Point your Sentry DSN at Buggregator. The format is the same for all platforms:

```dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1
```

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name (e.g., `buggregator`).

### Laravel

```dotenv
SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:8000/1
```

Install the SDK: [docs.sentry.io/platforms/php/guides/laravel](https://docs.sentry.io/platforms/php/guides/laravel/)

### Spiral Framework

```dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1
```

Install the SDK: [spiral.dev/docs/extension-sentry](https://spiral.dev/docs/extension-sentry/3.3/en)

### Symfony

```dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1
```

Install the SDK: [docs.sentry.io/platforms/php/guides/symfony](https://docs.sentry.io/platforms/php/guides/symfony/)

### Magento 2

Using [justbetter/magento2-sentry](https://github.com/justbetter/magento2-sentry):

```dotenv
CONFIG__SENTRY__ENVIRONMENT__DSN=http://sentry@127.0.0.1:8000/1
```

or in `app/etc/env.php`:

```php
'sentry' => [
    'dsn' => 'http://sentry@127.0.0.1:8000/1',
    ...
]
```

### WordPress

> `WP_ENVIRONMENT_TYPE` must be set to `local`. [Local](https://localwp.com/) does that by default.

1. Install [WP Sentry](https://wordpress.org/plugins/wp-sentry-integration/) (no need to activate).
2. Add to `wp-config.php`:

```php
if (defined('WP_ENVIRONMENT_TYPE') && 'local' === WP_ENVIRONMENT_TYPE) {
	define( 'WP_SENTRY_PHP_DSN', 'http://sentry@127.0.0.1:8000/1' );
	define( 'WP_SENTRY_ERROR_TYPES', E_ALL & ~E_NOTICE & ~E_USER_NOTICE );
	require_once __DIR__ . '/wp-content/plugins/wp-sentry-integration/wp-sentry.php';
}
```

### JavaScript

Buggregator serves a pre-configured Sentry JS bundle at `/sentry/<project>.js`:

```html
<script src="http://127.0.0.1:8000/sentry/1.js"></script>
```

Server-side env variables for customization:

```dotenv
SENTRY_JS_SDK_URL=https://browser.sentry-cdn.com/7.69.0/bundle.tracing.replay.min.js
SENTRY_JS_DSN_HOST=http://sentry@127.0.0.1:8000
```

### Other platforms

Any [Sentry SDK](https://docs.sentry.io/platforms/) works. Just set the DSN:

```dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1
```

## Secret key validation

By default, Buggregator accepts all events. To restrict access, set a secret key on the server:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e SENTRY_SECRET_KEY=my-secret-key \
  ghcr.io/buggregator/server:latest
```

Then include the key in the client DSN:

```dotenv
SENTRY_DSN=http://my-secret-key:sentry@127.0.0.1:8000/1
```

---

# SMS Gateway Interceptor

Your app sends SMS messages — OTP codes, delivery notifications, alerts. During development you don't want to send
real messages through Twilio or Vonage. Buggregator acts as a fake SMS gateway: point your app's SMS webhook URL at
Buggregator and every message shows up in the UI — with sender, recipient, message text, and detected provider.

## Use cases

- **OTP testing** — verify that verification codes are generated and sent correctly.
- **Notification preview** — see the exact text your users will receive.
- **Provider migration** — switch between Twilio, Vonage, Plivo etc. and verify the payload format.
- **Validation feedback** — use explicit provider URLs to catch missing required fields before going to production.

## How it works

Buggregator exposes a single `/sms` endpoint. When your app sends an HTTP POST with SMS data, Buggregator:

1. **Auto-detects the provider** by inspecting request body fields (e.g. `MessageSid` → Twilio, `api_key`+`api_secret` → Vonage).
2. **Extracts** `from`, `to`, and `message` using provider-specific field mappings.
3. **Displays** the SMS in the UI with a colored provider badge.

If the payload doesn't match any known provider, the generic fallback tries common field names (`from`/`to`/`message`/`body`/`text`).

### Explicit provider URL

You can also specify the provider in the URL for stricter validation:

```
POST /sms/twilio       → forces Twilio field mapping + validates required fields
POST /sms/vonage       → forces Vonage field mapping + validates required fields
POST /sms              → auto-detects provider from payload
```

When using an explicit provider URL, Buggregator validates that all required fields are present. If something is missing:
- The HTTP response returns **422** with a JSON error listing missing fields.
- The event is **still captured** in the UI with validation warnings highlighted in red.

This way your app sees the error (like it would from a real provider), and you can inspect the full payload in Buggregator.

### Project support

Append a project name as an additional URL segment:

```
POST /sms/twilio/myproject    → explicit provider + project
POST /sms/myproject           → auto-detect + project
```

## Supported providers

Over 40 providers are auto-detected. Here are the most common ones:

| Provider | Detect fields | From | To | Message |
|----------|--------------|------|-----|---------|
| Twilio | `MessageSid`, `Body` | `From` | `To` | `Body` |
| Vonage | `api_key`, `api_secret` | `from`, `msisdn` | `to` | `text` |
| Plivo | `MessageUUID` | `From`, `src` | `To`, `dst` | `Text` |
| Sinch | `batch_id`, `body` | `from` | `to` | `body` |
| Infobip | `messages` | `from` | `to` | `text` |
| MessageBird | `originator`, `recipients` | `originator` | `recipients` | `body` |
| Telnyx | `messaging_profile_id` | `from` | `to` | `text` |
| Bandwidth | `applicationId`, `text` | `from` | `to` | `text` |
| Brevo | `sender`, `recipient`, `content` | `sender` | `recipient` | `content` |
| Clickatell | `from`, `to`, `text` | `from` | `to` | `text` |
| SMS.ru | `api_id`, `msg` | `from` | `to` | `msg` |
| SMSC | `login`, `psw`, `phones` | `sender` | `phones` | `mes` |
| Generic | _(always matches)_ | `from`/`From`/`sender` | `to`/`To`/`recipient` | `message`/`body`/`text` |

Full list: Twilio, Vonage, Plivo, Sinch, Infobip, MessageBird, Telnyx, Bandwidth, Brevo, Termii, Clickatell, MessageMedia, Lox24, Unifonic, Yunpian, Octopush, GatewayApi, SevenIo, SmsFactor, Redlink, OvhCloud, Smsc, 46elks, Mobyt, Smsapi, Sendberry, TurboSms, SimpleTextin, Isendpro, RingCentral, ClickSend, SMS.ru, SMS Aero, Devino, IQSms, MTS, Beeline, Megafon.

## Configuration

### Symfony Notifier

Symfony's Notifier component uses DSN-based transport configuration. Every SMS bridge has a configurable host — change it to point at Buggregator.

```dotenv
# Default (sends to real Twilio):
TWILIO_DSN=twilio://SID:TOKEN@default?from=+1234567890

# Point to Buggregator (explicit provider URL for validation):
TWILIO_DSN=twilio://SID:TOKEN@127.0.0.1:8000/sms/twilio?from=+1234567890

# Or use auto-detect:
TWILIO_DSN=twilio://SID:TOKEN@127.0.0.1:8000/sms?from=+1234567890
```

Same pattern for any Symfony SMS bridge:

```dotenv
# Vonage
VONAGE_DSN=vonage://KEY:SECRET@127.0.0.1:8000/sms/vonage?from=MyApp

# Plivo
PLIVO_DSN=plivo://AUTH_ID:AUTH_TOKEN@127.0.0.1:8000/sms/plivo?from=+1234567890

# Sinch
SINCH_DSN=sinch://ACCOUNT_ID:AUTH_TOKEN@127.0.0.1:8000/sms/sinch?from=+1234567890
```

> In Docker Compose, replace `127.0.0.1:8000` with the Buggregator service name (e.g., `buggregator:8000`).

### Laravel

Laravel doesn't have built-in SMS, but if you use an HTTP-based SMS package, you can override the API base URL:

```php
// Example: sending directly via HTTP
Http::post('http://127.0.0.1:8000/sms/twilio', [
    'MessageSid' => Str::uuid(),
    'From' => '+1234567890',
    'To' => $user->phone,
    'Body' => "Your code is {$code}",
]);
```

### Any language / any framework

Send an HTTP POST to Buggregator with the provider's payload format:

```bash
# Twilio format
curl -X POST http://127.0.0.1:8000/sms/twilio \
  -H "Content-Type: application/json" \
  -d '{"MessageSid":"SM123","From":"+1234","To":"+5678","Body":"Hello!"}'

# Generic format (auto-detect)
curl -X POST http://127.0.0.1:8000/sms \
  -H "Content-Type: application/json" \
  -d '{"from":"+1234","to":"+5678","message":"Hello!"}'

# Test validation (missing required fields)
curl -X POST http://127.0.0.1:8000/sms/twilio \
  -H "Content-Type: application/json" \
  -d '{"From":"+1234","To":"+5678"}'
# Returns 422: {"error":"validation_failed","gateway":"twilio","missing_fields":["MessageSid","Body"]}
# But the event is still visible in Buggregator UI with warnings!
```

Both `application/json` and `application/x-www-form-urlencoded` are accepted.

---

# SMTP — Email Testing

Your app sends emails — registration confirmations, password resets, notifications. You need to verify they look
correct without actually delivering them. Buggregator includes a fake SMTP server: point your app's mail config at
port `1025` and every email shows up in the UI. No Mailhog, no Mailtrap, no external services — just another
module in the same Buggregator instance where you already see your logs and exceptions.

![smtp](https://github.com/buggregator/server/assets/773481/8dd60ddf-c8d8-4a26-a8c0-b05052414a5f)

## Use cases

- **Email template testing** — preview HTML emails with a desktop/mobile viewport switcher to check responsive layouts.
- **Transactional email verification** — make sure the right recipients, subject, and content are set before going to production.
- **Attachment testing** — verify that attachments are generated correctly and can be downloaded.
- **All in one place** — see emails next to the exceptions, logs, and dumps from the same request flow.

## What you see in the UI

- **HTML preview** — rendered email with desktop/mobile device viewport switcher.
- **Plain text** — the plain text version of the email.
- **Addresses** — From, To, CC, BCC, Reply-To organized by type.
- **Attachments** — download or preview any attached file. Inline images display correctly in the HTML preview.
- **Raw source** — the raw MIME source for debugging encoding or header issues.

## Configuration

Point your app's SMTP settings to `127.0.0.1:1025`. No authentication required.

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name (e.g., `buggregator`).

### Laravel

```dotenv
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
```

### Spiral Framework

```dotenv
MAILER_DSN=smtp://127.0.0.1:1025
```

### Symfony

```dotenv
MAILER_DSN=smtp://127.0.0.1:1025
```

### Magento 2

```dotenv
CONFIG__DEFAULT__SYSTEM__SMTP__TRANSPORT="smtp"
CONFIG__DEFAULT__SYSTEM__SMTP__HOST="127.0.0.1"
CONFIG__DEFAULT__SYSTEM__SMTP__PORT="1025"
```

or via CLI:

```bash
bin/magento config:set system/smtp/transport smtp
bin/magento config:set system/smtp/host 127.0.0.1
bin/magento config:set system/smtp/port 1025
```

### WordPress

Save to the [mu-plugins](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/) directory (e.g., `smtp.php`):

```php
<?php
/**
 * Plugin Name: MU Buggregator SMTP
 */

if (! defined('WP_ENVIRONMENT_TYPE') || 'local' !== WP_ENVIRONMENT_TYPE) {
	return;
}

add_action( 'phpmailer_init', function( $phpmailer ) : void {
	$phpmailer->isSMTP();
    $phpmailer->Host = '127.0.0.1';
    $phpmailer->Port = 1025;
}  );
```

### Any other app

Any application that can send email via SMTP works. Set host to `127.0.0.1` and port to `1025`.

---

# Configuration — Single Sign-On (SSO)

Buggregator supports Single Sign-On (SSO) for secure user authentication.

There is a list of supported SSO providers:

- [Auth0](https://auth0.com/)
- [Kinde](https://kinde.com/)

This integration allows users to authenticate with external identity providers, providing
a secure and seamless sign-in experience.

## Auth0

First, you need to have an Auth0 account. If you don't have one, you can [sign up](https://auth0.com/signup) for free.

After creating an account, follow these steps:

1. **Enable Authentication**: Set the environment variable `AUTH_ENABLED` to `true` to enable authentication features in
   your application.

2. **Auth provider**: Set the environment variable `AUTH_PROVIDER` to `auth0` to specify that you are using Auth0 as
   your authentication provider.

3. **Create an Application**: Log in to your account and create a new "Regular Web Application". After creating, you
   will see a `Domain`, `Client ID` and `Client Secret` that you will need to use in the next steps.

4. **Configure Settings**: Set up the following environment variables with the appropriate values from your
   application:

    - `AUTH_PROVIDER_URL`: The URL of your app domain, e.g., `https://<domain>.auth0.com`
    - `AUTH_CLIENT_ID`: The client ID provided by app.
    - `AUTH_CLIENT_SECRET`: The client secret provided by app.
    - `AUTH_CALLBACK_URL`: The callback URL that app will redirect to after authentication,
      e.g., `http://buggregator.server/auth/sso/callback`. Where `buggregator.server` is the domain of your server.
    - `AUTH_SCOPES`: The scopes for which permissions are granted, typically include `openid`, `email`, and `profile`.

5. **Set Up Callback URL**: In your Auth0 application settings, configure the callback URL to point to
   the `http://buggregator.server/auth/sso/callback` endpoint. Where `buggregator.server` is the domain of your
   Buggregator server.

Finally, your `.env` file should look like this:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=auth0
AUTH_PROVIDER_URL=https://<domain>.auth0.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_SCOPES=openid,email,profile
```

## Kinde

First, you need to have a Kinde account. If you don't have one, you
can [sign up](https://app.kinde.com/auth/cx/_:nav&m:register&psid:83976d64db58431da88130f1f883d9a4) for free.

After creating an account, follow these steps:

1. **Enable Authentication**: Set the environment variable `AUTH_ENABLED` to `true` to enable authentication features in
   your application.

2. **Auth provider**: Set the environment variable `AUTH_PROVIDER` to `kinde`.

3. **Add an Application**: Log in to your account and add a new "Back-end web" application. After creating, you will
   see a `Domain`, `Client ID` and `Client Secret` that you will need to use in the next steps.

4. **Configure Settings**: Set up the following environment variables with the appropriate values from your
   application:

    - `AUTH_PROVIDER_URL`: The URL of your app domain, e.g., `https://<domain>.kinde.com`
    - `AUTH_CLIENT_ID`: The client ID provided by app.
    - `AUTH_CLIENT_SECRET`: The client secret provided by app.
    - `AUTH_CALLBACK_URL`: The callback URL that app will redirect to after authentication,
      e.g., `http://buggregator.server/auth/sso/callback`. Where `buggregator.server` is the domain of your server.
    - `AUTH_LOGOUT_URL`: The callback URL that app will redirect to after authentication,
      e.g., `http://buggregator.server/auth/sso/logout`.
    - `AUTH_SCOPES`: The scopes for which permissions are granted, typically include `openid`, `email`, and `profile`.

5. **Set Up Callback URL**: In your application settings, configure the allowed callback URLs to point to
   the `http://buggregator.server/auth/sso/callback` endpoint.

6. **Set Up Login URL**: In your application settings, configure the callback URL to point to
   the `http://buggregator.server/auth/sso/login` endpoint.

7. **Set Up Logout URL**: In your application settings, configure the allowed logout redirect URLs to point to
   the `http://buggregator.server/auth/sso/logout` endpoint.

Finally, your `.env` file should look like this:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=kinde
AUTH_PROVIDER_URL=https://<domain>.kinde.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_LOGOUT_URL=http://<server_address>/auth/sso/logout
AUTH_SCOPES=openid,email,profile
```

## Other Providers

Buggregator supports Auth0 and Kinde for now. You can try to use other SSO providers using the same steps. If it works,
please update our documentation with your results. This will help us support more options and help others too.

## Verifying the Configuration

Once you set the environment variables, start your Buggregator server. You should see a Login page with an option to
sign in. If everything is set up right, clicking this option will take you to the provider's login page.

![image](https://github.com/buggregator/server/assets/773481/3bc5dd4b-b8ac-4e2c-a9c0-5707dd053d0b)

After logging in successfully, users will be redirected back to the Buggregator server and logged in. You will see the
user's profile information in the bottom left corner of the app.

![image](https://github.com/buggregator/frontend/assets/773481/6f996c5e-f43a-4f5e-8da4-71f83110c7ba)

### Troubleshooting

If you encounter issues during the authentication process, ensure that:

- All environment variables are correctly set without any typos.
- The callback URL in your configuration matches the `AUTH_CALLBACK_URL` you specified.

---

# VarDumper — Variable Dumps

You call `dump()` or `dd()` and the output lands in the browser response, mixes with HTML, or gets lost in CLI
output. With Buggregator, dumps go to a dedicated TCP server and show up in a clean UI — alongside your logs,
exceptions, and everything else. No browser pollution, no output buffering issues, no lost dumps in long-running
processes.

![var-dumper](https://github.com/buggregator/server/assets/773481/b77fa867-0a8e-431a-9126-f69959dc18f4)

## Use cases

- **Long-running apps** (RoadRunner, Swoole, queue workers) — `dd()` doesn't print to a browser here, but Buggregator catches it.
- **API development** — dump variables without breaking JSON responses.
- **Microservices** — collect dumps from all services in one place.
- **IDE integration** — click the source location to jump straight to the file in your editor.

## What you see in the UI

- **Dumped value** — full variable content with type information, rendered as an interactive expandable tree.
- **Source location** — file and line where `dump()` was called. Clickable — opens in your IDE.
- **Variable name and label** — custom labels if provided.
- **Syntax highlighting** — for text-only dumps (see below).

## Setup

Install the Symfony VarDumper component:

```bash
composer require --dev symfony/var-dumper
```

Set two env variables to redirect output to Buggregator:

```dotenv
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=127.0.0.1:9912
```

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name (e.g., `VAR_DUMPER_SERVER=buggregator:9912`).

That's it. Use `dump()` and `dd()` as usual — the output goes to Buggregator.

If your project doesn't use `.env` files, set via PHP:

```php
$_SERVER['VAR_DUMPER_FORMAT'] = 'server';
$_SERVER['VAR_DUMPER_SERVER'] = '127.0.0.1:9912';
```

## Performance tip

Large objects with deep nesting can slow down the browser. Limit the preview depth on the events list page:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  -e VAR_DUMPER_PREVIEW_MAX_DEPTH=3 \
  ghcr.io/buggregator/server:latest
```

The full dump is still available when you open the event detail page.

## Syntax highlighting

Dump a text string with syntax highlighting using [Buggregator Trap](../trap/what-is-trap.md):

```php
$code = <<<PHP
<?php

declare(strict_types=1);

echo 'Hello, World!';
PHP;

trap($code)->context(language: 'php');
```

![image_2024-05-01_00-39-56](https://github.com/buggregator/frontend/assets/773481/9cddfbfa-e3a3-427e-a987-0f4aa1bdb504)

## Buggregator Trap

Consider using [Buggregator Trap](../trap/what-is-trap.md) instead of raw VarDumper — it uses VarDumper under the
hood but adds extra features like `trap()`, `tr()`, and `td()` helpers.

---

# Configuration — Webhooks

Webhooks are a useful way to help Buggregator communicate in real-time with other applications when certain events
happen. This guide simplifies setting up and managing webhooks for enhancing automation and integration with other
tools.

This guide will help you understand how to set up and use webhooks.

### What is a Webhook?

A webhook allows applications to share information as soon as specific events occur. Unlike regular APIs that require
checking for updates periodically, webhooks provide this information automatically, saving time and resources.

### Why Use Webhooks in Buggregator?

- **Automate Tasks:** Automatically trigger actions in other services like [n8n](https://n8n.io/) when events happen in
  Buggregator.
- **Integrate with Other Tools:** Connect Buggregator with various tools like messaging apps, issue tracking software,
  or custom apps effortlessly.

## Docker Configuration

Currently, Buggregator does not have an admin interface for managing webhooks. Instead, you manage them through
configuration files within a Docker container.

**Here's how you can mount a volume containing webhook configurations:**

```bash
docker run --pull always \
  -v /path/to/webhooks:/app/runtime/configs \
  ghcr.io/buggregator/server:latest
```

or using `docker-compose`:

```yaml
buggregator-server:
  ...
  volumes:
    - /path/to/webhooks:/app/runtime/configs
```

## Configuring a Webhook

Place each webhook configuration in a YAML file within the `runtime/configs` directory. Each configuration file should
contain one webhook setup.

Here’s what a typical webhook configuration looks like in a YAML file `sentry.webhook.yaml`:

```yaml
webhook:
  event: sentry.received
  url: http://example.com/webhook
  headers:
    Content-Type: application/json
    Secret-Key: my-secret-key
  verify_ssl: false
  retry_on_failure: true
```

> **Note:** The webhook configuration file name should have the following pattern: `<name>.webhook.yaml` or `<name>.webhook.yml`.

**Key Components of a Webhook Configuration:**

- **Event:** The specific event in Buggregator that will trigger the webhook.
- **URL:** Where the webhook sends data.
- **Headers:** Any additional headers needed for the webhook request.
- **Verify SSL:** Choose whether to check SSL certificates during the webhook call.
- **Retry on Failure:** If the webhook should retry sending data if the first attempt fails. (3 retries with exponential
  backoff)

> **Note:** You can test webhooks using tools like https://webhook.site.

### Types of Events Supported:

Buggregator can currently handle the following events:

- `sentry.received`
- `monolog.received`
- `var-dumper.received`
- `ray.received`
- `inspector.received`
- `http-dump.received`
- `profiler.received`
- `smtp.received`

## Delivery Tracking

Buggregator tracks every webhook delivery attempt. You can view the delivery history for each webhook via the API,
including the response status code and payload. This helps you diagnose issues when webhooks fail to reach their
destination.

---

# XHProf — Performance Profiling

Your app is slow and you don't know why. Memory grows and you can't find the leak. XHProf profiling with
Buggregator lets you see exactly which functions consume CPU, wall time, and memory — without setting up
Blackfire or any paid profiling service. Profile data goes to the same Buggregator where you already see
your exceptions and logs.

Watch introduction video on [YouTube](https://www.youtube.com/watch?v=2QbgjIVnz78).

## Use cases

- **Find slow functions** — the Call Graph and Top Functions table show exactly where time is spent.
- **Detect memory leaks** — track memory allocation per function in long-running workers and daemons.
- **Measure optimizations** — compare two profiler runs side-by-side to verify your changes actually helped.
- **Profile any request** — works with web requests, CLI commands, queue jobs, and any PHP code.
- **All in one place** — profiling data next to exceptions, logs, and dumps in the same dashboard.

## Analysis modes

### Call Graph

Function calls as a tree. Nodes colored from white to dark red — the darker, the more resources consumed.

![xhprof-callgraph](https://github.com/buggregator/server/assets/773481/1cf3c587-c1df-4742-8fcd-54a320c86252)

### Flame Graph

Stacked function calls showing where time is spent. Useful for spotting repetitive or time-consuming operations.

![xhprof-flamegraph](https://github.com/buggregator/server/assets/773481/5f75e271-527d-4c6b-a0b1-a3558f8bac51)

### Top Functions

Ranked table of the most expensive function calls — CPU time, wall time, memory, and call count.

![xhprof-top-func](https://github.com/buggregator/server/assets/773481/43dbe4c8-ac23-4cfb-8715-f5141093618f)

### Profile Comparison

Compare two profiler runs side-by-side. See performance deltas (faster/slower) for CPU time, wall clock time,
and memory usage, with per-function percentage changes.

## Setup

### 1. Install the XHProf extension

```bash
pear channel-update pear.php.net
pecl install xhprof
```

### 2. Install the profiler package

#### Laravel

```bash
composer require --dev maantje/xhprof-buggregator-laravel
```

[Package documentation](https://github.com/maantje/xhprof-buggregator-laravel)

#### Spiral Framework

```bash
composer require --dev spiral/profiler:^3.0
```

[Package documentation](https://github.com/spiral/profiler/tree/3.0)

#### Any PHP project

```bash
composer require --dev spiral-packages/profiler
```

```php
use SpiralPackages\Profiler\Profiler;
use SpiralPackages\Profiler\DriverFactory;
use SpiralPackages\Profiler\Storage\WebStorage;
use Symfony\Component\HttpClient\NativeHttpClient;

$storage = new WebStorage(
    new NativeHttpClient(),
    'http://127.0.0.1/api/profiler/store',
);

$profiler = new Profiler(
    storage: $storage,
    driver: DriverFactory::detect(),
    appName: 'My app',
    tags: ['env' => 'local'],
);

$profiler->start();

// Your code here

$profiler->end();
```

### 3. Configure the endpoint

```dotenv
PROFILER_ENDPOINT=http://profiler@127.0.0.1:8000
PROFILER_APP_NAME="My app"
```

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name.

## Custom client integration

If you're building a custom profiler client, there are three ways to send data:

- **HTTP auth** — add `profiler` to the URL: `http://profiler@127.0.0.1:8000`
- **Header** — send `X-Buggregator-Event: profiler` or `X-Profiler-Dump: true`
- **Endpoint** — POST to `/api/profiler/store`

---

# Contributing to Buggregator

We're excited to invite you to contribute to the project! Your involvement is crucial, whether it's reporting bugs,
suggesting new features, or any other form of contribution. To get started,
simply [create an issue](https://github.com/buggregator/server/issues) or submit a pull request on our GitHub
repository.

In our repository, we categorize issues that are open for community contribution using
the [`for contributors`](https://github.com/buggregator/server/issues?q=is%3Aissue+is%3Aopen+label%3A%22for+contributors%22)
label. This makes it easier for you to find ways to participate.

Additionally, we use labels such as `c:easy`, `c:medium`, and `c:difficult` to indicate the complexity level of issues,
helping you choose tasks that match your skill level.

## Benefits

Contributing to open source projects offers a wealth of benefits, particularly for junior developers.

**Here's why you should consider getting involved:**

1. **Learning Through Practical Experience:** Open source projects provide a platform to work with new technologies and
   frameworks that you might not encounter in your regular job. It's a fantastic way to broaden your technical horizons.
2. **Building a Professional Network:** By participating in open source, you connect with a global community of
   developers. This network is invaluable for exchanging knowledge, learning from others' experiences, and sharing your
   own insights.
3. **Enhancing Your Résumé:** Contributions to open source are often highly regarded by employers. They showcase your
   proactive nature, technical skills, and ability to collaborate effectively in a team.
4. **Gaining Insight into Best Practices:** Engaging with open source projects exposes you to code reviews and feedback
   from various developers. This experience is crucial for understanding diverse coding styles and improving your own
   coding practices.
5. **Making a Real-World Impact:** Your contributions can significantly influence the project and its users. The
   satisfaction of seeing your code being used and appreciated by others is incredibly rewarding.

**Help us enhance Buggregator and make a real difference!**

**We appreciate any contributions to help make Buggregator better!**

## Repositories

There are the following repositories in the Buggregator project:

1. [Server](https://github.com/buggregator/server). Manages and sends events to the client. It also serves as a REST API
   endpoint for event requests.
2. [Frontend](https://github.com/buggregator/frontend). Allows clients to view incoming events like variable dumps.
3. [Trap](https://github.com/buggregator/trap). A lightweight alternative to the full Buggregator server, designed for
   local debugging.
4. [Documentation](https://github.com/buggregator/docs). Contains all the documentation for the Buggregator project.
5. [Site](https://github.com/buggregator/buggregator.dev). The official website for Buggregator.
6. [PHPStorm Plugin](https://github.com/buggregator/phpstorm-plugin). A plugin for PHPStorm that integrates with
   Buggregator.

---

# Contributing — Documentation

Buggregator uses [VitePress](https://vitepress.dev/) for its documentation. This makes it easy to contribute to the
project's documentation by following the steps below.

## Getting Started

### Clone the Repository

First of all you need to clone the repository to your local machine.

```bash
git clone git@github.com:buggregator/docs.git
```

> **Note**: If you don't have access to the repository, you can fork it and clone your forked repository.

### Install Dependencies

After cloning the repository, navigate to the project directory and install the dependencies.

```bash
npm install
```

### Start the Development Server

To start the development server and preview the documentation, run the following command:

```bash
npm run docs:dev
```

This command will start a local development server and open the documentation in your default browser.

## Structure

The documentation is structured as follows:

- `docs/`: Contains the documentation files.
- `docs/.vitepress/config.mts`: Site configuration and navigation.

All you need is to edit the markdown files in the `docs/` directory. If you want to add a new page, create a new
markdown file in the `docs/` directory and add it to the navigation in the `docs/.vitepress/config.mts` file.

---

That's it! You're now ready to contribute to the Buggregator documentation.

---

# Contributing — Frontend side

[The Frontend Part](https://github.com/buggregator/frontend) is what users interact with. It displays the events and
information processed by the server in a user-friendly way. Users can see live updates of events like errors or logs.

## Key Technologies:

- [VueJs 3](https://v3.vuejs.org/) - This framework builds the interactive user interface.
- [TailwindCSS](https://tailwindcss.com/) - Styles the frontend, making it look good and responsive.
- [Storybook](https://storybook.js.org/) - Helps us develop and organize UI components.

This architecture supports a robust system for monitoring and managing application events. As a contributor, your work
in either part plays a crucial role in enhancing Buggregator's functionality and user experience. If you have any
specific areas you're interested in or questions about the architecture, feel free to ask!

## Server requirements

1. NodeJS >=20.x (22.x is prefare)
2. Yarn >=1.22.x

## Installation

1. Clone repository `git clone https://github.com/buggregator/frontend.git`
2. Install dependencies `yarn install`
3. Run NodeJS server `yarn dev`
4. Open http://localhost:3000

In dev mode you are able to see Storybook components in isolation with mocked data by the link http://localhost:6006.

---

### Now you can start developing your own features and share them with the community!

---

# Contributing — Server side

[The Server Part](https://github.com/buggregator/server) is where all the data processing and management happen. It's
crucial for handling the information that flows through Buggregator.

1. **Event Processing:** This part receives information (like errors or logs) from applications. It organizes and
   processes these events.

2. **API Communication:** It also communicates with clients through REST API, sending and receiving data as needed.

## Key Technologies:

It's built on a foundation of robust and reliable technologies, including the Spiral Framework, RoadRunner, Centrifugo
and Doltdb.

- [Spiral Framework](https://spiral.dev/) - A PHP framework that's the foundation of our server.
- [RoadRunner](https://roadrunner.dev/) - Manages different server tasks like HTTP, TCP, queues, and caching.
- [Centrifugo](https://centrifugal.dev/) - Handles real-time messaging through WebSockets.
- [Doltdb](https://github.com/dolthub/dolt) - A SQL database that's built on top of a Git repository.

## Server requirements

1. Minimum PHP version: 8.2

## Installation

Here are two ways to install the server:

1. **Docker:** The easiest way to get started is by using Docker. To set up environment for local development read
   the [development environment setup guide](../cookbook/docker-install).
2. **Manual:** If you prefer to install the server manually, follow the [manual installation guide](../cookbook/manual-install.md).

---

# Cookbook — Dev environment using docker compose

Hey, developer! 🎉 This guide will help you quickly set up a local dev environment for Buggregator.

## 1. Clone the Repository

Start by cloning the repository:

```bash
git clone git@github.com:buggregator/server.git
cd server
```

> **Note:** If you don't have access, fork the repository and clone your fork instead.

## 2. Install Dependencies

Run the following to install PHP dependencies:

```bash
composer install
```

## 3. Build and Start the Docker Environment

The repository includes a Docker Compose setup for a local development environment, including the Buggregator server,
PostgreSQL, and service with examples.

### Build Docker Images

```bash
make build
```

### Start the Server

```bash
make up
```

> **Note:** Make sure you have make installed on your system. If not, you need to install it first.

This will:

- Start the Buggregator server.
- Spin up a PostgreSQL database.
- Launch the example server for testing features.

#### Mounted Directories in Docker Setup

The Docker Compose setup uses **mounted directories** to ensure that changes made to your local files are immediately
reflected inside the running containers. This makes development faster and more seamless.

1. **Application Code**  
   Local directory: `./app`  
   Mounted in the container: `/app/app`

2. **Runtime Files**  
   Local directory: `./runtime`  
   Mounted in the container: `/app/runtime`

3. **Vendor Directory**  
   Local directory: `./vendor`  
   Mounted in the container: `/app/vendor`

## 4. Access the Application

Once the server is up, you can access the following:

- **Buggregator:** [http://buggregator.localhost](http://buggregator.localhost)
- **Examples:** [http://examples.buggregator.localhost](http://examples.buggregator.localhost)

## 5. Environment Configuration (Optional)

The default `.env` file is pre-configured, but you can customize it if needed:

```bash
cp .env.sample .env
```

## 6. Stop the Server

To stop the server and clean up, run:

```bash
make down
```

> **Note:** If any services like PostgreSQL don't stop, you can manually kill them with `docker ps` and `docker kill`.

---

That's it! 🚀 Your Buggregator dev environment is ready. Happy coding! 😊

---

# Cookbook — Manual install dev environment

Hey, developer! 🎉 This guide will help you quickly set up a local dev environment for Buggregator.

## Clone the Repository

First of all you need to clone the repository to your local machine.

```bash
git clone git@github.com:buggregator/server.git
```

> **Note**: If you don't have access to the repository, you can fork it and clone your forked repository.

## Install Dependencies

After cloning the repository, navigate to the project directory and install the dependencies.

```bash
composer install
```

## Install RoadRunner

Buggregator uses RoadRunner as an application server. To install RoadRunner, run the following command:

```bash
./vendor/bin/rr get
```

## Download required binaries

Buggregator requires some binaries to be downloaded.

- Centrifugo server for Websockets
- DoltDB for local database

To download these binaries, run the following command:

```bash
cd ./bin
chmod +x ./get-binaries.sh
./get-binaries.sh
```

This script will download the required binaries to the `./bin` directory.

## Create a new local database

Buggregator uses DoltDB as a local database. To create a new database, run the following command:

```bash
mkdir .db
./bin/dolt --data-dir=.db sql -q "create database buggregator;"
```

## Configure the Environment

Create a new `.env` file in the project root directory:

```bash
cp .env.sample .env
```

Generate a new application key:

```bash
php app.php encrypt:key --mount=.env
```

Update the `.env` file with your configuration settings.

```dotenv
# Queue
QUEUE_CONNECTION=roadrunner

# Broadcast
BROADCAST_CONNECTION=centrifugo

# Monolog
MONOLOG_DEFAULT_CHANNEL=roadrunner
MONOLOG_DEFAULT_LEVEL=DEBUG

# Database
PERSISTENCE_DRIVER=db
DB_DRIVER=mysql # mysql, pgsql
DB_DATABASE=buggregator
DB_HOST=127.0.0.1
DB_USERNAME=root
DB_PASSWORD=

# Turn off cache for tokenizer
TOKENIZER_CACHE_TARGETS=false
```

## Start the Application

To start the application, run the following command:

```bash
./rr serve
```

RoadRunner will start the application server and also Centrifugo and DoltDB servers.

> **Warning**: In some cases when you stop the application, the Centrifugo or DoltDB servers may not stop. Kill them
> manually using the following commands:

```bash
killall centrifugo
killall dolt
killall php
```

When the application is running, you can access it at `http://localhost:8082`.


---

Now you have successfully set up your development environment for Buggregator. Happy coding! 🚀

---

# Getting Started

## Quick Start

Make sure [Docker](https://docs.docker.com/get-docker/) is installed on your machine, then run:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  -p 127.0.0.1:9913:9913 \
  -p 127.0.0.1:9914:9914 \
  ghcr.io/buggregator/server:latest
```

Open http://127.0.0.1:8000 in your browser. Done.

## Ports

Each port serves a specific module. You only need to expose the ports for the features you use:

| Port | Protocol | Module | What it does |
|------|----------|--------|-------------|
| **8000** | HTTP | [Sentry](./config/sentry.md), [Ray](./config/ray.md), [Inspector](./config/inspector.md), [HTTP Dumps](./config/http-dumps.md), [XHProf](./config/xhprof.md) | Web UI + HTTP-based event ingestion. This is the only required port. |
| **1025** | SMTP | [Fake SMTP Server](./config/smtp.md) | Captures outgoing emails. Point your app's SMTP config here (e.g., `MAIL_HOST=127.0.0.1`, `MAIL_PORT=1025`). |
| **9912** | TCP | [Symfony VarDumper](./config/var-dumper.md) | Receives `dump()` / `dd()` output. Set `VAR_DUMPER_FORMAT=server` and `VAR_DUMPER_SERVER=127.0.0.1:9912`. |
| **9913** | TCP | [Monolog](./config/monolog.md) | Receives log records via Monolog's `SocketHandler` in JSON format. |
| **9914** | TCP | [XHProf Profiler](./config/xhprof.md) | Receives XHProf profiling data from `spiral/profiler` and compatible clients. |

If you only need specific features, omit the unused ports. For example, VarDumper only:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  ghcr.io/buggregator/server:latest
```

## Installation Options

### Docker Compose

Add Buggregator as a service in your `docker-compose.yml`:

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
      - 127.0.0.1:9912:9912
      - 127.0.0.1:9913:9913
      - 127.0.0.1:9914:9914
```

If Buggregator is part of an existing Docker Compose stack, other services can reach it by its service name.
Configure your app's `.env` to point at the container:

```dotenv
RAY_HOST=ray@buggregator
RAY_PORT=8000
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator:9912
SENTRY_LARAVEL_DSN=http://sentry@buggregator:8000/1
LOG_CHANNEL=socket
LOG_SOCKET_URL=buggregator:9913
MAIL_HOST=buggregator
MAIL_PORT=1025
```

### Kubernetes

Deploy Buggregator as a `Deployment` + `Service` in your cluster:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: buggregator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: buggregator
  template:
    metadata:
      labels:
        app: buggregator
    spec:
      containers:
        - name: buggregator
          image: ghcr.io/buggregator/server:latest
          ports:
            - containerPort: 8000
            - containerPort: 1025
            - containerPort: 9912
            - containerPort: 9913
            - containerPort: 9914
---
apiVersion: v1
kind: Service
metadata:
  name: buggregator
spec:
  selector:
    app: buggregator
  ports:
    - name: http
      port: 8000
    - name: smtp
      port: 1025
    - name: var-dumper
      port: 9912
    - name: monolog
      port: 9913
    - name: profiler
      port: 9914
```

Other pods can reach Buggregator at `buggregator:8000` (or the corresponding port) within the cluster.

### Manual Installation

See the [manual installation guide](./cookbook/manual-install.md) for running Buggregator without Docker
(RoadRunner + Centrifugo binaries).

## Other Image Tags

All available tags can be found in the [GitHub Container Registry](https://github.com/buggregator/server/pkgs/container/server).

| Tag | Description |
|-----|-------------|
| `latest` | Latest stable release. **Recommended.** |
| `dev` | Latest development build. Includes newest features, may be less stable. |
| `X.Y` (e.g., `1.0`) | A specific release version, pinned. |

Example with the dev tag:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  -p 127.0.0.1:9913:9913 \
  -p 127.0.0.1:9914:9914 \
  ghcr.io/buggregator/server:dev
```

## Security

By default, all ports are bound to `127.0.0.1` (localhost only). This prevents external access.

> **Warning:** If you remove the `127.0.0.1:` prefix (e.g., `-p 8000:8000`), the port becomes accessible from
> outside your machine. Only do this if you understand the implications.

For production-like setups, consider enabling [SSO authentication](./config/sso.md) to restrict access to the UI.

---

# What is Buggregator?

## Debug everything. Install nothing.

One `docker run`. Exceptions, dumps, emails, profiling, logs — all in one real-time UI.
Works with the SDKs you already have. No cloud account. No code changes.

**Watch introduction video on [YouTube](https://www.youtube.com/watch?v=yKWbuw8xN_c)**

**Project repository:** https://github.com/buggregator/server

![Cover image](https://github.com/buggregator/server/assets/773481/47491a3c-57a3-4b40-b82e-37976afdf708)

## How it works

Buggregator runs *beside* your application as a standalone server — not inside it. Your codebase doesn’t change.
Your dependencies don’t change. You already have the SDKs installed (Sentry, VarDumper, Monolog, Ray) — they just
need a different address in your `.env`.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  ghcr.io/buggregator/server:latest
```

Open http://127.0.0.1:8000 and start debugging. That’s it.

> For local debugging without Docker, use [Buggregator Trap](./trap/what-is-trap.md) — a lightweight PHP CLI
> alternative with zero configuration.

## When you need it

- You have a **long-running PHP app** (RoadRunner, FrankenPHP, Swoole, Octane, queue workers) and `dd()` is not an option.
- You want to see **exceptions with stack traces** like in Sentry, but don’t want to set up Sentry for local dev.
- You need to **profile performance** and find memory leaks or slow functions.
- You want to **test emails** your app sends without a real mail server.
- You want to **capture SMS messages** without sending real ones through Twilio or Vonage.
- You have **multiple services** (microservices, Docker Compose) and want all debug data in one place.
- You want to **inspect HTTP requests** your app makes to external APIs.
- You just need a better `dump()` — with syntax highlighting, IDE links, and no browser pollution.
- You want to **replace 8 separate local dev tools** with one free, self-hosted server.

## Key Features

### [XHProf Profiler](/config/xhprof) — Performance

Find slow functions and memory leaks. Buggregator visualizes profiling data as a **Call Graph**, **Flame Graph**,
and **Top Functions** table. **Compare two runs** side-by-side to verify your optimizations actually helped.

![xhprof](https://github.com/buggregator/server/assets/773481/d69e1158-599d-4546-96a9-40a42cb060f4)

### [Sentry Compatibility](/config/sentry) — Exceptions

Replace Sentry for local development. See exceptions with full **stack traces**, **breadcrumbs**, **request details**,
**device/browser info**, tags, and context. All Sentry SDKs are supported — PHP, JavaScript, Python, and more.

![sentry](https://github.com/buggregator/server/assets/773481/e979fda5-54c8-42cc-8224-a1c5d828569a)

### [Fake SMTP Server](/config/smtp) — Emails

Capture all outgoing emails. Preview HTML (with mobile/desktop viewport switcher), plain text, all addresses,
attachments, and raw source. Just point your app’s SMTP config to port `1025`.

![smtp](https://github.com/buggregator/server/assets/773481/8dd60ddf-c8d8-4a26-a8c0-b05052414a5f)

### [SMS Gateway](/config/sms) — SMS Messages

Capture SMS messages your app sends through Twilio, Vonage, Plivo, and 40+ other providers. Point your SMS
webhook URL at Buggregator and see every message with sender, recipient, text, and detected provider. Use
explicit provider URLs (`/sms/twilio`) for field validation — missing fields are highlighted in the UI while
your app gets a proper error response.

### [HTTP Dumps](/config/http-dumps) — Requests

Capture and inspect HTTP requests: method, URI, headers, cookies, POST data, uploaded files. Get a ready-to-use
**cURL command** for any captured request.

![http dumps](https://github.com/buggregator/server/assets/773481/fc823390-b490-4bbb-a787-44471eca9fb6)

### [Monolog Server](/config/monolog) — Logs

Collect application logs in real time. See log level, channel, message, context, extra fields, and source location.
Supports all PSR-3 levels.

![monolog](https://github.com/buggregator/server/assets/773481/21919110-fd4d-490d-a78e-41242d329885)

### [Symfony VarDumper](/config/var-dumper) — Variable Dumps

Redirect `dump()` output to Buggregator instead of your browser. See variables with full type info, source location,
and syntax highlighting. Click on file paths to open them in your IDE.

![var-dumper](https://github.com/buggregator/server/assets/773481/b77fa867-0a8e-431a-9126-f69959dc18f4)

### [Spatie Ray](/config/ray) — Debug Tool

A free alternative to the Ray app. Supports 18 payload types: logs, exceptions, SQL queries, Eloquent models,
Laravel jobs, mail previews, performance measurements, and more. Works with PHP, JavaScript, Ruby, Go, and Bash.

![ray](https://github.com/buggregator/server/assets/773481/168b27f7-75b1-4837-b0a1-37146d5b8b52)

### [Inspector Compatibility](/config/inspector) — Transactions

Monitor application performance. View transaction duration, memory usage, HTTP request details, and timeline
breakdown to identify bottlenecks.

![inspector](https://github.com/buggregator/server/assets/773481/ab002ecf-e1dc-4433-90d4-0e42ff8c0ab3)

## JetBrains IDE Plugin

Don’t want to leave your IDE? The [Buggregator plugin for JetBrains IDEs](https://plugins.jetbrains.com/plugin/26344-buggregator)
brings dumps, logs, and debug data directly into PhpStorm, IntelliJ IDEA, WebStorm, and other JetBrains products.
No need to switch windows — everything is in a panel next to your code, with all IDE shortcuts working.

The plugin launches [Buggregator Trap](/trap/what-is-trap) from your project and provides two views:
- **Web UI** — the full Buggregator interface embedded in the IDE’s built-in browser.
- **Terminal** — text-based output for quick inspection.

Install from **Settings** > **Plugins** > **Marketplace** > search "Buggregator", or visit the
[plugin page](https://plugins.jetbrains.com/plugin/26344-buggregator).

Read more in the [plugin documentation](/config/phpstorm-plugin).

## Also included

- **Event pinning** — pin important events so they don’t get lost.
- **Event screenshots** — export any event as an image to share with your team.
- **Keyboard shortcuts** — press `?` to see all shortcuts. Navigate with `j`/`k`, switch modules with `1`-`8`.
- **IDE integration** — click file paths to open them in VS Code, PhpStorm, or [14 other IDEs](/config/var-dumper). Custom path mappings for Docker.
- **Dark / Light themes** — follows your system preference or set manually.
- **[Multi-project support](/config/projects)** — separate events by project or team.
- **[Webhooks](/config/webhooks)** — trigger external actions when events are received.
- **[Prometheus metrics](/config/metrics)** — monitor event counts with Grafana.
- **[SSO authentication](/config/sso)** — Auth0 and Kinde support.
- **[External database](/config/external-db)** — PostgreSQL or MySQL for persistent storage.

## Tech stack

- [Spiral Framework](https://spiral.dev/) + [RoadRunner](https://roadrunner.dev/) (HTTP, WebSocket, TCP, Queue)
- [Vue 3](https://vuejs.org/) + [TypeScript](https://www.typescriptlang.org/) + [Vite](https://vite.dev/)
- [TailwindCSS](https://tailwindcss.com/) + [Pinia](https://pinia.vuejs.org/)
- [Centrifugo](https://centrifugal.dev/) (real-time WebSocket messaging)

## Contributing

Buggregator is open-source. Contributions are welcome — bugs, features, docs.

[Contribution guidelines](./contributing.md) · [GitHub](https://github.com/buggregator/server)

---

# Using Buggregator docs with AI assistants

Buggregator documentation is available in a machine-readable format so that AI assistants (ChatGPT, Claude, Cursor,
Windsurf, GitHub Copilot, and others) can read it and help you set up, configure, and debug issues.

## Quick start

Give your AI assistant this URL:

```
https://docs.buggregator.dev/llms.txt
```

The assistant will read the index, understand what Buggregator is, and fetch the specific pages it needs to answer
your question.

### Example prompts

- "Read https://docs.buggregator.dev/llms.txt and help me set up Buggregator with my Laravel project"
- "I have a Symfony app. How do I send Monolog logs to Buggregator?"
- "Help me configure XHProf profiling for my PHP application"
- "What's the difference between Buggregator server and Trap?"

## Available endpoints

| URL | What it contains | When to use |
|-----|-----------------|-------------|
| [`/llms.txt`](https://docs.buggregator.dev/llms.txt) | Index with page descriptions | When the assistant supports browsing — it picks the relevant pages |
| [`/llms-full.txt`](https://docs.buggregator.dev/llms-full.txt) | Complete documentation in one file | Best for most assistants — give full context in one shot |
| `/<page>.md` | Individual page without frontmatter | When you only need a specific topic |

### Per-page URLs

If you only need help with a specific integration, you can point the assistant to a single page:

- `https://docs.buggregator.dev/config/sentry.md` — Sentry setup
- `https://docs.buggregator.dev/config/smtp.md` — SMTP / email testing
- `https://docs.buggregator.dev/config/xhprof.md` — XHProf profiling
- `https://docs.buggregator.dev/config/monolog.md` — Monolog logs
- `https://docs.buggregator.dev/config/var-dumper.md` — Symfony VarDumper
- `https://docs.buggregator.dev/config/ray.md` — Spatie Ray
- `https://docs.buggregator.dev/getting-started.md` — Installation guide

## How it works

These files follow the [llms.txt](https://llmstxt.org/) convention — a standard way to provide documentation
to AI models. The content is the same as the regular docs, just formatted for machine consumption (plain markdown,
no HTML, no navigation chrome).

The files are generated automatically during the docs build, so they're always up to date with the latest
documentation.

---

# Trap — Commands

## `run`

### Description

The `run` command starts the Trap server, which listens for debug information on specified ports and
processes it using configured senders.

### Simple Example

```bash
vendor/bin/trap run
```

### Arguments and Options

| Option     | Short | Description                                             | Default                  |
|------------|-------|---------------------------------------------------------|--------------------------|
| `--port`   | `-p`  | Port(s) to listen on (can be specified multiple times)  | `1025, 8000, 9912, 9913` |
| `--sender` | `-s`  | Sender type(s) to use (can be specified multiple times) | `console`                |
| `--ui`     | -     | Enable web UI (with optional port specification)        | `false`                  |

### Port Configuration Details

By default, Trap runs on multiple ports simultaneously: `1025, 8000, 9912, 9913`. All ports listen for the same data,
but this multi-port setup makes it compatible with various debugging tools that have their own default ports:

- Port `1025`: Default SMTP port for email testing
- Port `8000`: Used for HTTP dumps
- Port `9912`: Default port for Symfony VarDumper
- Port `9913`: Default for Monolog socket handler

If you want to listen on just one specific port, you can specify it:

```bash
vendor/bin/trap run -p 8000
```

This will make Trap listen only on port `8000`.

### Examples

Start with default settings:

```bash
vendor/bin/trap run
```

Listen on specific ports:

```bash
vendor/bin/trap run --port=8888
# or
vendor/bin/trap run -p 8888
```

Listen on multiple ports:

```bash
vendor/bin/trap run --port=8888 --port=9999
# or
vendor/bin/trap run -p 8888 -p 9999
```

Enable the web UI on default port:

```bash
vendor/bin/trap run --ui
```

Use environment variables for configuration:

```bash
TRAP_TCP_PORTS=8888,9999 TRAP_UI_PORT=8080 vendor/bin/trap run --ui
```

### Available Senders

Trap supports multiple methods ("senders") for outputting the debug information, allowing you to choose where your debug
dumps are sent:

- **Console**: Outputs dumps directly in the console.
- **Server**: Sends dumps to a remote Buggregator server for centralized management and review.
- **File**: Saves dumps to a file, useful for auditing or detailed offline analysis.

By default, dumps are displayed in the console. However, you can configure multiple senders simultaneously to suit your
workflow and requirements. For example, to use the console, file, and server senders together:

| Sender         | Description                                      |
|----------------|--------------------------------------------------|
| `console`      | Outputs debug information to the console         |
| `file`         | Writes events to files in JSON format            |
| `file-body`    | Writes event body content to separate files      |
| `mail-to-file` | Stores received emails to files                  |
| `server`       | Forwards events to a Buggregator server instance |


```bash
vendor/bin/trap run --sender=console --sender=file
```

## `test`

### Description

The `test` command sends various types of test data to the Trap server to verify that it's working correctly. This
includes XHProf data, var dumps, emails, Sentry reports, and binary data.

### Simple Example

```bash
vendor/bin/trap test
```

### Arguments and Options

The `test` command doesn't accept any arguments or options.

### Example

To send test data to a running Trap instance:

```bash
# First, start the trap server in one terminal
vendor/bin/trap run

# Then, in another terminal, run the test command
vendor/bin/trap test
```

This will:

1. Send XHProf profiling data
2. Execute various `trap()` dumps
3. Send test emails (both simple and multipart)
4. Send Sentry store and envelope data
5. Send binary data

---

## `joke`

### Description

The `joke` command prints a random joke using the trap framework. It's a fun addition that also demonstrates the trap
functionality.

### Simple Example

```bash
vendor/bin/trap joke
```

### Arguments and Options

The `joke` command doesn't accept any arguments or options.

### Example

To display a random joke:

```bash
vendor/bin/trap joke
```

The joke output will be displayed using the same output mechanism as other trap messages, which can be a good way to
verify that your trap setup is working correctly in a lightweight manner.

## Environment Variables

Trap can be configured using environment variables:

| Variable                    | Description                                | Default                             |
|-----------------------------|--------------------------------------------|-------------------------------------|
| `TRAP_TCP_PORTS`            | Comma-separated list of ports to listen on | `1025,8000,9912,9913`               |
| `TRAP_TCP_HOST`             | Host interface to bind to                  | `127.0.0.1`                         |
| `TRAP_TCP_POLLING_INTERVAL` | Socket polling interval in microseconds    | `1000`                              |
| `TRAP_UI_PORT`              | Web UI port                                | `8000`                              |
| `TRAP_UI_HOST`              | Web UI host interface                      | `127.0.0.1`                         |
| `TRAP_MAIN_LOOP_INTERVAL`   | Main loop interval in microseconds         | `100`                               |
| `TRAP_XHPROF_PATH`          | Path to XHProf files                       | Read from PHP's `xhprof.output_dir` |
| `TRAP_XHPROF_SORT`          | XHProf edges sorting algorithm (0-3)       | `3`                                 |

---

# Trap — Getting Started

There are several ways to get started with Trap, depending on your needs and preferences.

## Standalone Binary (No Project Dependencies)

Download and extract the pre-compiled binary for your platform. This method allows you to use Trap across multiple PHP
projects without modifying their dependencies.

**Available for platforms:**

- Linux (amd64, arm64)
- macOS (amd64, arm64)
- Windows (amd64)

> **Note:** Binaries can be found on release page https://github.com/buggregator/trap/releases

```bash
# Download (example for Linux amd64)
curl -L -o trap.tar.gz https://github.com/buggregator/trap/releases/latest/download/trap-1.13.13-linux-amd64.tar.gz

# Extract the archive
tar -xzf trap.tar.gz
rm trap.tar.gz

# Make executable
chmod +x trap

# Run
./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 or in the browser.

## Composer Installation

To use Trap into your project, simply add it as a development dependency via Composer:

```bash
composer require --dev buggregator/trap -W
```

After installation, you can start the debugging server using:

```bash
vendor/bin/trap
```

Once Trap is running, you can start debugging with the `trap()` function:

```php
// Basic variable dump
trap($user);

// Named variable dumps
trap(id: $userId, email: $userEmail);

// Dump and continue using the value
$response = trap($api->getResponse())->return();

// Set dump depth for nested objects
trap($complexObject)->depth(3);
```

## User Interface

By adding the `--ui` flag when starting the Trap server, you can automatically open the web interface. This allows for a
more intuitive and graphical interaction with your debug data.

```bash
./trap --ui
# or
vendor/bin/trap --ui
```

And just open the URL in your browser: [http://127.0.0.1:8000](http://127.0.0.1:8000).

## What's Next?

- Read more about the `trap()` function in the [Usage](./usage.md) section.
- Explore the [Commands](./commands.md) for additional functionality.

---

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

---

# Trap — What is it?

Trap is a powerful, lightweight debugging tool designed to supercharge your PHP development experience. It
serves as an excellent alternative to Symfony VarDumper by providing all the functionality you need for debugging with
the addition of a clean, intuitive user interface built right in.

**Project repository:** https://github.com/buggregator/trap
> Star the project to show your support and help us grow! ⭐️ We appreciate your support!

## What Makes Trap Special

Unlike traditional debugging tools that output to the console or directly into your application's response, Trap
captures debugging information and presents it both in a dedicated dashboard and console. This separation keeps your
application output clean while giving you a comprehensive view of all debugging data in one place.

### Key Features:

- **Zero Configuration**: Works immediately after installation with sensible defaults.
- **Cross-Project Compatibility**: Allows to debug multiple applications simultaneously with a single Trap instance
- **Dashboard Interface:** It features the same user-friendly dashboard as the full Buggregator Server, allowing for
  seamless monitoring and management of debug outputs directly from the web.
- **Standalone Binary**: Use without adding dependencies to your project on Windows, Linux, or MacOS.
- **Console Application:** Includes a mini-server written entirely in PHP, eliminating the need for Docker or other
  container technology. This makes it easier to deploy and use in a variety of development environments.
- **Multiple Handlers:** Trap supports various handlers for debugging such as **Symfony VarDumper**,
  **Monolog**,**Sentry**, **SMTP**, **HTTP dumps**, **Ray**, and more. This versatility allows developers to tailor the
  debugging process to their specific needs and existing development stack.
- **Protobuf Debugging:** Offers an improved way to work with Google Protocol Buffers (protobuf) by providing clearer
  and more concise debugging outputs.



## Console Application

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

### Symfony/var-dumper (proto)

![var-dumper](https://github.com/buggregator/trap/assets/4152481/f4c855f5-87c4-4534-b72d-5b19d1aae0b0)

### Binary Data

![Binary Data](https://github.com/buggregator/trap/assets/4152481/cd8788ed-b10c-4b9a-b2e2-baa8912ea38d)

### SMTP Mail Trap

![smtp](https://github.com/buggregator/trap/assets/4152481/b11c4a7f-072a-4e66-b11d-9bbd3177bfe2)

### HTTP Dump

![http-dump](https://github.com/buggregator/trap/assets/4152481/48201ce6-7756-4402-8954-76a27489b632)