README

Official Alby error-tracking SDK for PHP 8.2+.

Captures uncaught exceptions, errors, and anything you explicitly report, then ships them to your Alby project where an AI agent can auto-open a fix task.

Install

composer require alby/report

Requires PHP 8.2+, ext-curl, ext-json. No other runtime dependencies.

Use

use Alby\Report\Alby;

Alby::init([
    'dsn'         => getenv('ALBY_DSN'),  // https://<key>@alby.sh/ingest/v1/<app-id>
    'release'     => '1.4.2',
    'environment' => 'production',
]);

// Uncaught exceptions and fatal errors are sent automatically.

// Manual report:
try {
    doThing();
} catch (\Throwable $e) {
    Alby::captureException($e);
}

// Non-error events:
Alby::captureMessage('Failed to acquire lease', 'warning');

// Enrich the scope:
Alby::setUser(['id' => 'u_412', 'email' => 'ada@example.com']);
Alby::setTag('region', 'eu-west-3');
Alby::setContext('billing_tenant', ['plan' => 'pro', 'seats' => 12]);
Alby::addBreadcrumb(['type' => 'http', 'message' => 'GET /api/orders/42']);

// Before exit (e.g. in a worker):
Alby::flush(2000);

The SDK buffers events in memory and ships them on flush() or at register_shutdown_function time. Sending is synchronous with a bounded queue of 100 events; long-running workers should call Alby::flush() at the end of each unit of work.

Laravel

The package auto-discovers its service provider, so nothing else is needed on Laravel 5.5+. Publish the config:

php artisan vendor:publish --tag=alby-report-config

Then set your DSN in .env:

ALBY_DSN=https://<key>@alby.sh/ingest/v1/<app-id>
ALBY_RELEASE=1.4.2

Reporting exceptions

Laravel 11+ (bootstrap/app.php):

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(fn (\Throwable $e) => \Alby\Report\Alby::captureException($e));
})

Laravel ≤10 (app/Exceptions/Handler.php):

public function register(): void
{
    $this->reportable(fn (\Throwable $e) => \Alby\Report\Alby::captureException($e));
}

Optional breadcrumbs

In config/alby-report.php:

'breadcrumbs' => [
    'queries' => true,   // DB query breadcrumbs
    'routes'  => true,   // Route-matched breadcrumbs
],

Options

Wire protocol

This SDK speaks the Alby Ingest Protocol v1. If you're writing an SDK for a new runtime, start there.

Links

• Website: alby.sh
• Report issues: GitHub Issues
• Other SDKs: alby-sdk-js · alby-sdk-browser · alby-sdk-python

License

MIT — © Alby.