Laravel SDK

Install

composer require mybeast/errors-laravel
php artisan vendor:publish --tag=mybeast-errors-config

The package registers itself. The second line copies the config to config/mybeast-errors.php; it works without it, from .env alone.

.env

MYBEAST_ERRORS_URL=https://services.my-beast.com/errors
MYBEAST_ERRORS_PUBLIC_KEY=pk_…
MYBEAST_ERRORS_SECRET=sk_…
MYBEAST_ERRORS_SIGNING_KEY=sig_…
MYBEAST_ERRORS_WEBHOOK_SECRET=whsec_…
MYBEAST_ERRORS_ENVIRONMENT=production

While the URL or the server secret is missing or malformed, nothing is captured or sent. The SDK never throws at boot and never breaks a page. Where each value comes from: the quickstart.

Config

Artisan commands

The scheduler must run for mybeast:errors-flush to: php artisan schedule:work, or cron's schedule:run.

What is captured

The SDK hooks the exception handler's reportable(), so whatever Laravel reports is captured, and Laravel's dontReport list still applies. Each error carries:

• the exception and the ones before it, with source lines around your own frames,
• the last 30 breadcrumbs: SQL without its values, log lines, the route or job,
• the route, the action, and the names of its parameters and fields, never their values,
• the release, the environment, and who it happened to, by id,
• the request's id as your log lines carry it, so the issue opens exactly those lines in Logs: the one mybeast/logs-laravel gives the request when you have it, else a proxy's X-Request-Id.

An error is written to a spool file first, never the database, which may be what failed. The spool is sent right after the response, after each queued job, and every minute by the scheduler. While Errors can't be reached, errors wait there, up to 5,000 files. Under Octane each request starts with a clean trail.

The Errors facade

MyBeast\Errors\Laravel\Facades\Errors. No alias is registered: import it.

identifyUsing() is explained in Say who it happened to, clientConfig() in Catch browser errors.

Scrubbing

Before anything leaves your app, e-mail addresses, IBANs, Finnish personal identity codes, phone numbers and tokens are replaced, in messages and source lines alike, and so are long random parts of a URL's path: /reset-password/9f8e… leaves as /reset-password/[token], while UUIDs and ULIDs stay readable. A URL keeps its query's keys, never their values. Add rules of your own:

use MyBeast\Errors\Laravel\Facades\Errors;

// AppServiceProvider::boot(): your own rule, after the built-in ones.
Errors::scrubUsing(fn (string $text): string => preg_replace('/\bCUST-\d+\b/', '[customer]', $text));

Errors runs the built-in rules again on arrival. More in Data and privacy.

Erasing a person or an account

use MyBeast\Errors\Laravel\Facades\Errors;

// In a queued job with retries: an erasure is never lost to a network blip.
$erased = Errors::eraseSubject($user->id);       // a person
$erased = Errors::eraseAccount($user->team_id);  // an account, whoever it happened to

Each returns how many rows went or were emptied, or null while the SDK is off or has no server secret. Each throws MyBeast\Errors\Laravel\ErasureFailed when Errors doesn't confirm it, so call them from a queued job with retries. Errors still in the spool when it runs reach Errors after it and are kept: delay the job a few minutes, or erase again then. An erasure that finds nothing returns 0.

Testing

Errors::fake() keeps what would be sent in memory, so nothing reaches the service, and gives you assertions:

use MyBeast\Errors\Laravel\Facades\Errors;

public function test_a_failed_payment_is_reported(): void
{
    $fake = Errors::fake();

    $this->post('/checkout', ['plan' => 'pro'])->assertStatus(500);

    $fake->assertCaptured(fn (array $event) => $event['exception_class'] === PaymentFailed::class);
}

• assertCaptured(?Closure $matching): at least one error was captured, matching the closure if given.
• assertNothingCaptured(): nothing was.
• last() and events: the last captured error, and all of them, as arrays.

In a suite that doesn't fake it, switch the SDK off in phpunit.xml:

<env name="MYBEAST_ERRORS_ENABLED" value="false"/>