Grouping Related Audit Log Entries with batch_uuid

Every LogEntry that ModelScribe writes to a driver carries a batchUuid — a UUID string that is persisted in the batch_uuid column of the log table. By default, each individual Eloquent event (a created, updated, or deleted call) produces its own LogEntry with a freshly generated UUID, so under normal automatic logging each entry is its own batch. The real power of batch_uuid emerges when you want to tie multiple related entries together so you can retrieve all the changes that happened as part of a single logical operation.

How `batch_uuid` Is Generated

The batch_uuid value is set inside the LogEntry constructor. If no UUID is provided, Str::uuid() is called automatically:

// From DTOs/LogEntry.php
public function __construct(
    public readonly ScribeEvent $event,
    public readonly string $logName,
    public readonly ?string $description,
    public readonly ?Model $subject,
    public readonly ?Model $causer,
    public readonly array $properties,
    public readonly array $tags = [],
    public readonly ?string $url = null,
    public readonly ?string $ipAddress = null,
    public readonly ?string $userAgent = null,
    ?string $batchUuid = null,
) {
    $this->batchUuid = $batchUuid ?? (string) Str::uuid();
}

This means every log entry always has a batch_uuid, even when you never think about batching. For automatic observer-driven logs, each event gets its own unique UUID. For manual logs created via ModelScribe::log(), the UUID is likewise generated per call — unless you take deliberate steps to share one across multiple calls (see below).

Querying Entries by Batch UUID

Because batch_uuid is a plain column on the ScribeLog model, you can query it like any other attribute using Eloquent:

use HypathBel\ModelScribe\Models\ScribeLog;

$entries = ScribeLog::where('batch_uuid', $batchUuid)->get();

Querying by batch_uuid is a practical way to display all changes that occurred during a single HTTP request or background job — for example, building an “undo this operation” feature, or providing a detailed audit trail grouped by the action that triggered it.

Grouping Manual Logs with a Shared Batch UUID

The LogEntry constructor accepts an optional ?string $batchUuid = null parameter. Since ModelScribe::log() creates a LogEntry internally, you can coordinate a shared batch UUID across multiple manual log calls by passing a consistent identifier via the properties array, or by building LogEntry objects directly if you are working at a lower level.

For most manual-logging use cases, the recommended pattern is to generate a UUID once and include it in the properties of each related call so you can group and retrieve the entries together:

use Illuminate\Support\Str;
use HypathBel\ModelScribe\Facades\ModelScribe;
use HypathBel\ModelScribe\Enums\ScribeEvent;

$batchId = (string) Str::uuid();

// Note: batch_uuid grouping for manual logs can be tracked via properties
ModelScribe::log(
    event: ScribeEvent::Custom,
    logName: 'orders',
    description: 'Order created',
    subject: $order,
    properties: ['batch_id' => $batchId]
);

ModelScribe::log(
    event: ScribeEvent::Custom,
    logName: 'payments',
    description: 'Payment charged',
    subject: $payment,
    properties: ['batch_id' => $batchId]
);

You can then retrieve all entries associated with that batch by filtering on the JSON batch_id property:

use HypathBel\ModelScribe\Models\ScribeLog;

$entries = ScribeLog::where('properties->batch_id', $batchId)->get();

Querying the Native `batch_uuid` Column

For automatic observer-driven entries, batch_uuid is always populated from the LogEntry value object. If you are building an integration that constructs LogEntry objects directly and passes them to a driver, you can supply a pre-generated UUID to group them:

use Illuminate\Support\Str;
use HypathBel\ModelScribe\DTOs\LogEntry;
use HypathBel\ModelScribe\Enums\ScribeEvent;

$sharedUuid = (string) Str::uuid();

$firstEntry = new LogEntry(
    event: ScribeEvent::Updated,
    logName: 'orders',
    description: 'Status updated',
    subject: $order,
    causer: $user,
    properties: ['old' => ['status' => 'pending'], 'attributes' => ['status' => 'shipped']],
    batchUuid: $sharedUuid,
);

$secondEntry = new LogEntry(
    event: ScribeEvent::Updated,
    logName: 'shipments',
    description: 'Shipment dispatched',
    subject: $shipment,
    causer: $user,
    properties: ['old' => ['dispatched' => false], 'attributes' => ['dispatched' => true]],
    batchUuid: $sharedUuid,
);

Both entries will share the same batch_uuid in the database and can be fetched together:

use HypathBel\ModelScribe\Models\ScribeLog;

$entries = ScribeLog::where('batch_uuid', $sharedUuid)->get();

Getting Started

Core Concepts

Usage

Configuration

Maintenance

Grouping Related Audit Log Entries with batch_uuid

How `batch_uuid` Is Generated

Querying Entries by Batch UUID

Grouping Manual Logs with a Shared Batch UUID

Querying the Native `batch_uuid` Column

​How batch_uuid Is Generated

​Querying Entries by Batch UUID

​Grouping Manual Logs with a Shared Batch UUID

​Querying the Native batch_uuid Column

How `batch_uuid` Is Generated

Querying Entries by Batch UUID

Grouping Manual Logs with a Shared Batch UUID

Querying the Native `batch_uuid` Column