Laravel SDK

Install

composer require mybeast/audit-laravel
php artisan migrate

Laravel finds the service provider by itself. migrate creates the outbox table. To change the config in a file rather than in .env, publish it to config/mybeast-audit.php:

php artisan vendor:publish --tag=mybeast-audit-config

The .env lines

Two lines send events, from the project in Audit (its setup guide, or Secrets when id made the secret):

MYBEAST_AUDIT_URL=https://services.my-beast.com/audit
MYBEAST_AUDIT_SECRET=sk_…

Without them, or with a secret that isn't well-formed, events wait in the outbox. The rest are optional:

MYBEAST_AUDIT_ENABLED=true               # false: check events, write nothing
MYBEAST_AUDIT_CONNECTION=                 # the connection of the actions you record
MYBEAST_AUDIT_OUTBOX_TABLE=audit_outbox   # before the first migrate
MYBEAST_AUDIT_REQUEST_ID_HEADER=X-Request-Id

Configuration

A key that is missing or malformed reads as its default, never as an error when your app boots.

The outbox table

audit_outbox, or the name in outbox.table, on the connection in outbox.connection. A row goes once Audit has confirmed its event.

To run the migration as one of your own, set outbox.migrations to false in the published config and publish the migration:

php artisan vendor:publish --tag=mybeast-audit-migrations

Artisan commands

audit:ship ends with an error (exit code 1) when a run stops with events waiting, so your scheduler's monitoring sees it. It ends with 0 otherwise: also when another run holds the lock, and when the URL or the secret is missing, which it says. Send events to Audit says what each run does.

The Audit facade

MyBeast\Audit\Laravel\Facades\Audit:

• record(…) checks the event, writes it to the outbox and returns its id. It throws MyBeast\Audit\Laravel\Events\InvalidAuditEvent for an event Audit would refuse.
• fake() keeps events in memory from then on, and returns the fake with its assertions.
• ship() does what audit:ship does, and returns a report: kept, duplicates, refused, stopped (why it stopped, or null), configured, busy and sent().
• status() returns what waits: waiting, refused, oldest and last_error.

record()'s parameters, in order. The ones ending in a colon are best passed by name:

Actors and targets are MyBeast\Audit\Laravel\Events\Actor and Target. Record events says what each part is for.

Testing with the fake

Audit::fake() keeps events in memory: nothing is written to the outbox and nothing is sent. A wrong event still throws, so a test catches it.

use MyBeast\Audit\Laravel\Facades\Audit;

public function test_support_sees_the_customer(): void
{
    $audit = Audit::fake();

    $this->actingAs($operator)->get("/customers/{$customer->id}")->assertOk();

    $audit->assertRecorded('customer.viewed', fn (array $event) => $event['subject'] === $customer->user_id);
    $audit->assertRecordedTimes('customer.viewed', 1);
    $audit->assertNotRecorded('key.revealed');
}

• assertRecorded($action, $matching = null): at least one event of the action, matching the closure if you give one.
• assertRecordedTimes($action, $times): exactly that many.
• assertNotRecorded($action, $matching = null) and assertNothingRecorded().
• recorded($action = null, $matching = null) returns the events, each the array Audit would get: see The event.

Tests that don't fake it can set MYBEAST_AUDIT_ENABLED=false in phpunit.xml: events are checked and nothing is written.