roxblnfk / spiral-app

About Buggregator is a beautiful, lightweight debug server build on Laravel that helps you debug your app. It runs without installation on multiple platforms.

A server for debugging PHP applications and more.

Buggregator is a beautiful, lightweight standalone server built on Spiral Framework, NuxtJs and RoadRunner underhood. It helps debugging mostly PHP applications without extra packages.

It runs without installation on multiple platforms via docker and supports: Xhprof, Symfony var-dumper, Monolog, Sentry, SMTP catcher and Inspector.

Contents

1. Features
   • Xhprof profiler
   • Symfony VarDumper server
   • Fake SMTP server
   • Sentry server
   • Monolog server
   • Inspector
2. Installation
   • Docker image
   • Docker compose
3. Configuration
4. Contributing
5. License

---

1. Xhprof profiler

XHProf is a light-weight hierarchical and instrumentation based profiler. During the data collection phase, it keeps track of call counts and inclusive metrics for arcs in the dynamic callgraph of a program. It computes exclusive metrics in the reporting/post processing phase, such as wall (elapsed) time, CPU time and memory usage.

Installation

1. Install Xhprof extension One of the way to install Xhprof is to use PECL package.

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

2. Install the xhprof package

If you are using Spiral Framework you just need t install the spiral/profiler package.

composer require --dev spiral/profiler:^3.0

Configuration

PROFILER_ENDPOINT=http://127.0.0.1:8000/api/profiler/store
PROFILER_APP_NAME=My super app

Note: Read more about package usage in the documentation.

2. Symfony VarDumper server

The dump() and dd() functions output its contents in the same browser window or console terminal as your own application. Sometimes mixing the real output with the debug output can be confusing. That’s why this Buggregator can be used to collect all the dumped data.

Installation

composer require --dev symfony/var-dumper

Configuration

You should change dumper format to server for var-dumper component. There is a VAR_DUMPER_FORMAT env variable in the package to do it.

VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=127.0.0.1:9912 # Default value

via PHP

// Plain PHP
$_SERVER['VAR_DUMPER_FORMAT'] = 'server';
$_SERVER['VAR_DUMPER_SERVER'] = '127.0.0.1:9912';

Or you can also define this env var as follows:

VAR_DUMPER_FORMAT=server php app.php route:list

---

3. Fake SMTP server for catching mail

Buggregator also is an email testing tool that makes it super easy to install and configure a local email server. It sets up a fake SMTP server, and you can configure your preferred web applications to use Buggregator’s SMTP server to send and receive emails. For instance, you can configure a local WordPress site to use it for email deliveries.

Configuration

Env variables

// Spiral Framework or Symfony
MAILER_DSN=smtp://127.0.0.1:1025

# Laravel
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

---

4. Compatible with Sentry reports

Buggregator can be used to receive Sentry reports from your application. It's a lightweight alternative for local development. Just configure Sentry DSN to send data to Buggregator.

Spiral Framework

Spiral Framework is supported via a native package. You can read about integrations on official site

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

Laravel

Laravel is supported via a native package. You can read about integrations on official site

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

Other platforms

To report to Buggregator you’ll need to use a language-specific SDK. The Sentry team builds and maintains these for most popular languages.

You can find out documentation on official site

---

5. Monolog server

It can receive logs from monolog/monolog package via \Monolog\Handler\SocketHandler handler.

Spiral Framework

You can register socket handler for monolog via bootloader.

Bootloader example

<?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);
    }
}

Env variables

MONOLOG_DEFAULT_CHANNEL=socket
MONOLOG_SOCKET_HOST=127.0.0.1:9913

Laravel

Config

// 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'),
            ],
        ],
    ],
];

Env variables

LOG_CHANNEL=socket
LOG_SOCKET_URL=127.0.0.1:9913

Other PHP frameworks

Install monolog

composer require monolog/monolog

<?php

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

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

// Send records to the Buggregator
$log->warning('Foo');
$log->error('Bar');

---

6. Compatible with Inspector reports

Buggregator can be used to receive Inspector events from your application. It's a lightweight alternative for local development. Just configure Inspector client URL to send data to Buggregator.

Laravel settings

Laravel is supported via a native package. You can read about integrations on official site

INSPECTOR_URL=http://127.0.0.1:8000/api/inspector
INSPECTOR_API_KEY=test
INSPECTOR_INGESTION_KEY=1test
INSPECTOR_ENABLE=true

Other platforms

For PHP you can use inspector-apm/inspector-php package.

use Inspector\Inspector;
use Inspector\Configuration;

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

// ...

To report to Buggregator you’ll need to use a language-specific SDK. The Inspector team builds and maintains these for most popular languages.

Note: You can find out documentation on official site

---

Technological stack

• Spiral Framework
• RoadRunner Http, Websocket, TCP, Queue, Cache server in one bottle
• NuxtJs
• TailwindCSS

Installation

Docker image

You can run Buggregator via docker from Github Packages

Latest stable release

docker run --pull always -p 8000:8000 -p 1025:1025 -p 9912:9912 -p 9913:9913 ghcr.io/buggregator/server:latest

Latest dev release

docker run --pull always -p 8000:8000 -p 1025:1025 -p 9912:9912 -p 9913:9913 ghcr.io/buggregator/server:dev

Note: You can omit --pull always argument if your docker-compose doesn't support it.

Specific version

docker run -p 8000:8000 -p 1025:1025 -p 9912:9912 -p 9913:9913 ghcr.io/buggregator/server:v1.00

Note: You can omit unused ports if you use, for example, only var-dumper

docker run --pull always -p 9912:9912 ghcr.io/buggregator/server:latest

Using buggregator with docker compose

version: "2"
services:
    # ...

    buggregator:
        image: ghcr.io/buggregator/server:dev
        ports:
            - 8000:8000
            - 1025:1025
            - 9912:9912
            - 9913:9913

That's it. Now you open http://127.0.0.1:8000 url in your browser and collect dumps from your application.

Enjoy!

---

Contributing

There are several issues in this repo with unresolved issues, and it would be great if you help a community solving them.

Backend part

Server requirements

1. PHP 8.1

Installation

1. Clone repository git clone https://github.com/buggregator/spiral-app.git
2. Run composer composer install
3. Download RoadRunner binary vendor/bin/rr get-binary
4. Run composer cd frontend && yarn install
5. Run RoadRunner server ./rr serve

---

License

Buggregator is open-sourced software licensed under the MIT license.