https://github.com/alby-sh/alby-sdk-php
Official Alby error-tracking SDK for PHP 8.2+ and Laravel
https://github.com/alby-sh/alby-sdk-php
alby error-monitoring error-tracking laravel observability php sdk
Last synced: 1 day ago
JSON representation
Official Alby error-tracking SDK for PHP 8.2+ and Laravel
- Host: GitHub
- URL: https://github.com/alby-sh/alby-sdk-php
- Owner: alby-sh
- License: mit
- Created: 2026-04-20T01:19:26.000Z (7 days ago)
- Default Branch: main
- Last Pushed: 2026-04-20T10:20:24.000Z (7 days ago)
- Last Synced: 2026-04-22T00:38:09.885Z (5 days ago)
- Topics: alby, error-monitoring, error-tracking, laravel, observability, php, sdk
- Language: PHP
- Homepage: https://alby.sh
- Size: 34.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# alby/report
[](https://packagist.org/packages/alby/report)
[](https://packagist.org/packages/alby/report)
[](https://packagist.org/packages/alby/report)
[](https://github.com/alby-sh/alby-sdk-php/actions/workflows/ci.yml)
[](./LICENSE)
Official [Alby](https://alby.sh) 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
```bash
composer require alby/report
```
Requires PHP 8.2+, `ext-curl`, `ext-json`. No other runtime dependencies.
## Use
```php
use Alby\Report\Alby;
Alby::init([
'dsn' => getenv('ALBY_DSN'), // https://@alby.sh/ingest/v1/
'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:
```bash
php artisan vendor:publish --tag=alby-report-config
```
Then set your DSN in `.env`:
```
ALBY_DSN=https://@alby.sh/ingest/v1/
ALBY_RELEASE=1.4.2
```
### Reporting exceptions
**Laravel 11+ (`bootstrap/app.php`):**
```php
->withExceptions(function (Exceptions $exceptions) {
$exceptions->report(fn (\Throwable $e) => \Alby\Report\Alby::captureException($e));
})
```
**Laravel ≤10 (`app/Exceptions/Handler.php`):**
```php
public function register(): void
{
$this->reportable(fn (\Throwable $e) => \Alby\Report\Alby::captureException($e));
}
```
### Optional breadcrumbs
In `config/alby-report.php`:
```php
'breadcrumbs' => [
'queries' => true, // DB query breadcrumbs
'routes' => true, // Route-matched breadcrumbs
],
```
## Options
| Option | Type | Default | Notes |
|------------------|----------|-------------------------|-------|
| `dsn` | `string` | — (required) | From your Alby app settings. |
| `release` | `string` | `''` | Build version. Enables release tracking / auto-resolve. |
| `environment` | `string` | `APP_ENV` / `production`| `production` / `staging` / `dev` / anything. |
| `sample_rate` | `float` | `1.0` | Fraction of events actually sent, 0..1. |
| `server_name` | `string` | `gethostname()` | Attached to every event. |
| `auto_register` | `bool` | `true` | Install `set_exception_handler` + `set_error_handler` + `register_shutdown_function`. Chains to existing handlers. |
| `debug` | `bool` | `false` | SDK diagnostics to stderr. |
| `transport` | `Transport` | `CurlTransport` | Injectable transport (tests, alt delivery). |
| `breadcrumbs_max`| `int` | `100` | Ring-buffer cap. |
## Wire protocol
This SDK speaks the [Alby Ingest Protocol v1](./PROTOCOL_V1.md). If you're
writing an SDK for a new runtime, start there.
## Links
- Website: [alby.sh](https://alby.sh)
- Report issues: [GitHub Issues](https://github.com/alby-sh/alby-sdk-php/issues)
- Other SDKs: [alby-sdk-js](https://github.com/alby-sh/alby-sdk-js) · [alby-sdk-browser](https://github.com/alby-sh/alby-sdk-browser) · [alby-sdk-python](https://github.com/alby-sh/alby-sdk-python)
## License
MIT — © Alby.