Laravel Auditing

https://github.com/owen-it/laravel-auditing
Admin
Laravel Auditing is a Laravel package that tracks and audits changes to Eloquent models, providing a...
Tokens:48,590
Snippets:389
Trust Score:8.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### InstallCommand for auditing:install

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

The InstallCommand defines the auditing:install signature and handle method. Running the command publishes configuration and migrations, registers the AuditingServiceProvider in config/app.php, and prints 'Auditing installed successfully.' The output shows the expected messages.

```php
class InstallCommand extends Command
{
    protected $signature = 'auditing:install';
    protected $description = 'Install all of the Auditing resources';
}
```

```php
public function handle(): void
```

```bash
php artisan auditing:install
```

```text
# Publishing Auditing Configuration...
# Publishing Auditing Migrations...
Auditing installed successfully.
```

--------------------------------

### UserResolver configuration example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

Example configuration for the audit user resolver, specifying guards and the resolver class.

```php
// Config
'user' => [
    'morph_prefix' => 'user',
    'guards' => ['web', 'api'],
    'resolver' => \OwenIt\Auditing\Resolvers\UserResolver::class,
],
```

--------------------------------

### UrlResolver example output comments

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

Shows example values recorded by UrlResolver: a console command and a web request URL.

```php
// Console runs record e.g. 'php artisan db:seed'
// Web requests record e.g. 'https://example.com/articles/1/edit'
```

--------------------------------

### getTags() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-data-access.md

Example call to getTags() returning an array of tags, e.g., ['tenant:42', 'critical'].

```php
$audit->getTags(); // ['tenant:42', 'critical']
```

--------------------------------

### Install Laravel Auditing with Composer

Source: https://github.com/owen-it/laravel-auditing/wiki/Getting-Started

Install the Laravel Auditing package via Composer.

```bash
composer require owen-it/laravel-auditing
```

--------------------------------

### getAuditEvents() returning a list of events

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Example override returning a plain list of event names. The getter methods are derived as get<Event>EventAttributes.

```php
public function getAuditEvents(): array
{
    return ['created', 'updated', 'deleted', 'restored', 'published'];
}
```

--------------------------------

### readyForAuditing() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Shows how to check if a model is ready for auditing before proceeding, skipping if auditing is disabled or the event is not configured.

```php
if (! $article->readyForAuditing()) {
    return; // skip — auditing disabled or event not configured
}
```

--------------------------------

### auditSync usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-pivot-auditing.md

Example of syncing a relation with auditSync, passing a single category key.

```php
$changes = $article->auditSync('categories', [$secondCategory->getKey()]);
```

--------------------------------

### getMetadata() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-data-access.md

Example of calling getMetadata() on an audit instance. Shows array output and JSON output with the json: true parameter.

```php
$audit = $article->audits()->first();

$audit->getMetadata();
// ['audit_id' => 1, 'audit_event' => 'created', 'user_id' => 7, ...]

$audit->getMetadata(json: true);
// '{"audit_id":1,"audit_event":"created",...}'
```

--------------------------------

### preloadResolverData() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Example of calling preloadResolverData() on an article model and accessing the preloaded data. The 'ip_address' key is cached by IpAddressResolver, and 'user' contains the resolved user if non-empty.

```php
$article->preloadResolverData();

$article->preloadedResolverData['ip_address']; // cached by IpAddressResolver
$article->preloadedResolverData['user'];       // resolved user (or absent)
```

--------------------------------

### Using the Auditor facade

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditor.md

Example of using the facade to execute auditing on a model after setting the audit event to 'updated'.

```php
use \OwenIt\Auditing\Facades\Auditor;

$article->setAuditEvent('updated');
Auditor::execute($article);
```

--------------------------------

### enableAuditing() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-audit-control.md

Re-enables auditing for the Article model and creates a record that is audited again.

```php
Article::enableAuditing();

Article::factory()->create(); // audited again
```

--------------------------------

### Usage example for toAudit()

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Shows how to set an audit event and retrieve the payload. The payload contains keys like 'event', 'old_values', and 'new_values'.

```php
$article->setAuditEvent('created');
$payload = $article->toAudit();

$payload['event'];        // 'created'
$payload['old_values'];   // []
$payload['new_values'];   // ['title' => 'A Guide', ...]
```

--------------------------------

### Using the Database driver to audit a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/drivers.md

Example of instantiating the Database driver and calling audit() on a model, then retrieving the stored audit's key.

```php
$driver = new \OwenIt\Auditing\Drivers\Database();

$audit = $driver->audit($article);
$audit->getKey(); // stored audit id
```

--------------------------------

### getTable() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-trait.md

Calls getTable() on the Audit class. The output is 'audits' or the configured table name.

```php
Audit::getTable(); // 'audits' (or the configured table name)
```

--------------------------------

### Using user() to get the acting user

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-trait.md

Accesses the acting user via the user relationship. The example shows that the result is null when the change was made anonymously.

```php
$actingUser = $audit->user; // null when the change was made anonymously
```

--------------------------------

### Custom resolver class implementation

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

Example custom resolver that returns a tenant id. Must implement the Resolver contract.

```php
class TenantResolver implements \OwenIt\Auditing\Contracts\Resolver
{
    public static function resolve(Auditable $auditable)
    {
        return 1; // e.g. tenant id
    }
}
```

--------------------------------

### Using auditable() to get the audited model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-trait.md

Fetches an audit by ID and accesses the related audited model via the auditable relationship. The example shows how to retrieve the Article associated with the audit.

```php
$audit = Audit::find(1);
$article = $audit->auditable; // the audited Article
```

--------------------------------

### Define a custom audit driver

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example setting $auditDriver to a custom driver name.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    public $auditDriver = 'audit_logs'; // a custom driver registered in the container
}
```

--------------------------------

### Override generateTags

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example returning a dynamic tag based on the current tenant.

```php
public function generateTags(): array
{
    return ['tenant:' . $this->tenant_id];
}
```

--------------------------------

### withoutAuditing() restore-on-exception example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-audit-control.md

Shows that the auditing state is restored even if the callback throws an exception.

```php
try {
    Article::withoutAuditing(function () {
        throw new RuntimeException('boom');
    });
} catch (RuntimeException $e) {
    // handled
}

Article::isAuditingDisabled(); // false — state restored
```

--------------------------------

### Error handling example for toAudit()

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Demonstrates how to catch an AuditingException when an invalid audit event is set. The exception message is 'A valid audit event has not been set'.

```php
$article->setAuditEvent('not_an_event'); // resolves to null

try {
    $article->toAudit();
} catch (\OwenIt\Auditing\Exceptions\AuditingException $e) {
    // "A valid audit event has not been set"
}
```

--------------------------------

### auditSyncWithPivotValues() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-pivot-auditing.md

Example call to auditSyncWithPivotValues() syncing groups with a pivot value of 'role' => 'member'. Returns the sync() result and throws AuditingException.

```php
$changes = $user->auditSyncWithPivotValues(
    'groups',
    [$firstGroup->getKey(), $secondGroup->getKey()],
    ['role' => 'member']
);
```

--------------------------------

### Generate a resolver with artisan auditing:audit-resolver

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

Example command to generate a resolver named TenantResolver. It creates app/AuditResolvers/TenantResolver.php and outputs the reminder message to add the resolver to the audit.php config file.

```bash
php artisan auditing:audit-resolver TenantResolver
# creates app/AuditResolvers/TenantResolver.php
# "Add your new resolver to the resolvers array in audit.php config file."
```

--------------------------------

### transformAudit() example implementation

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Example override of transformAudit() that adds the current locale to the audit data. The method receives the assembled payload and returns the modified array.

```php
public function transformAudit(array $data): array
{
    $data['locale'] = App::getLocale();

    return $data;
}
```

--------------------------------

### withoutAuditing() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-audit-control.md

Skips auditing for a one-off backfill on the Article model, and optionally for all models when $globally is true.

```php
// Skip auditing for a one-off backfill
Article::withoutAuditing(function () {
    Article::factory()->create(); // not audited
});

// Skip auditing for ALL models during the callback
Article::withoutAuditing(function () {
    Article::factory()->create(); // not audited
    User::factory()->create();    // not audited either
}, true);
```

--------------------------------

### Listen to Auditing event

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Example listener for the Auditing event. Returning false aborts the audit, useful for blocking audits on foreign tenants.

```php
Event::listen(\OwenIt\Auditing\Events\Auditing::class, function (Auditing $event) {
    return $event->model->tenant_id === currentTenant(); // block foreign audits
});
```

--------------------------------

### auditSyncWithoutDetaching() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-pivot-auditing.md

Example call to auditSyncWithoutDetaching() syncing categories without detaching. Passes the relation name and an array containing the category key.

```php
$article->auditSyncWithoutDetaching('categories', [$category->getKey()]);
```

--------------------------------

### getAuditEvent() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Shows how to retrieve the current audit event from a model instance, e.g., 'updated'.

```php
$event = $article->getAuditEvent(); // e.g. 'updated'
```

--------------------------------

### Listen to Audited event

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Example listener for the Audited event. Natural place to notify external systems after an audit is stored.

```php
Event::listen(\OwenIt\Auditing\Events\Audited::class, function (Audited $event) {
    broadcast('audit.stored', $event->audit->getKey());
});
```

--------------------------------

### Define $auditInclude on a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example showing how to specify which attributes are recorded, only those listed are audited.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    public $auditInclude = ['title', 'content']; // only these are recorded
}
```

--------------------------------

### Resolve audit driver via facade

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditor.md

Example usage of the Auditor facade to resolve the audit driver for an $article model, returning a database driver instance.

```php
$driver = Auditor::auditDriver($article); // Database driver instance
```

--------------------------------

### auditSync with pivot values

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-pivot-auditing.md

Example of syncing with pivot values recorded as custom event data, using a key-value map for the pivot column.

```php
$user->auditSync('groups', [$group->getKey() => ['role' => 'admin']]);
```

--------------------------------

### Data flow diagram for auditing process

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/types.md

This ASCII diagram shows the flow of data through the auditing pipeline. It starts with an Eloquent model that implements the Auditable contract, passes through the AuditableObserver, then to Auditor::execute(), then to AuditDriver::audit(), and finally produces an Audit instance implementing Contracts\Audit. The transitionTo method allows the Audit to transition back to the model.

```text
Eloquent model (Auditable) ─▶ AuditableObserver ─▶ Auditor::execute() ─▶ AuditDriver::audit() ─▶ Audit (Contracts\Audit)
        ▲                                                                    │
        └────────────── transitionTo(Contracts\Audit) ◀─────────────────────┘
```

--------------------------------

### Consuming queue and dispatch events

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-observer.md

Example of consuming queue and dispatch events from application code. It aborts queueing for requests from a specific endpoint and observes successful writes.

```php
use Illuminate\Support\Facades\Event;
use OwenIt\Auditing\Events\DispatchingAudit;
use OwenIt\Auditing\Events\Audited;

// Abort queueing for requests coming from a specific endpoint
Event::listen(DispatchingAudit::class, function (DispatchingAudit $event) {
    if (str_contains($event->model->preloadedResolverData['url'] ?? '', '/internal')) {
        return false; // stops Auditor::execute for this model
    }

    return true;
});

// Observe successful writes (synchronous and queued paths both end here)
Event::listen(Audited::class, function (Audited $event) {
    logger()->info('Audit {id} stored', $event->audit->getKey());
});
```

--------------------------------

### Define $attributeModifiers on a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example mapping attribute definitions of encoders and redactors.

```php
public $attributeModifiers = [
    'email'    => \OwenIt\Auditing\Encoders\Base64Encoder::class,
    'password' => \OwenIt\Auditing\Redactors\RightRedactor::class,
];
```

--------------------------------

### Override getAuditTimestamps to return true

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example overriding the method to audit timestamp columns.

```php
public function getAuditTimestamps(): bool
{
    return true; // record created_at/updated_at/deleted_at changes
}
```

--------------------------------

### Define $auditExclude on a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example showing how to set the auditExclude property on a model to exclude specific attributes.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    public $auditExclude = ['internal_note', 'secret_key'];
}
```

--------------------------------

### isAuditingEnabled() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-audit-control.md

Checks if auditing is enabled, e.g., for an artisan command with audit.console disabled.

```php
if (! Article::isAuditingEnabled()) {
    // e.g. artisan command with audit.console disabled
}
```

--------------------------------

### getAuditEvents() returning an associative map

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Example override returning an associative map of event patterns to getter method names, supporting wildcards like 'state_*'.

```php
public function getAuditEvents(): array
{
    return [
        'created'  => 'getCreatedEventAttributes',
        'updated'  => 'getUpdatedEventAttributes',
        'state_*'  => 'getStateEventAttributes',
    ];
}
```

--------------------------------

### Full custom configuration for Laravel Auditing

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/configuration.md

Example configuration file (config/audit.php) showing all available options: enabled, strict, exclude, events, resolvers, threshold, and queue settings. Use this as a template for customizing the auditing behavior in your application.

```php
// config/audit.php
return [
    'enabled'   => env('AUDITING_ENABLED', true),
    'strict'    => true,
    'exclude'   => ['internal_note'],
    'events'    => ['created', 'updated', 'deleted', 'restored', 'published'],
    'resolvers' => [
        'ip_address' => \OwenIt\Auditing\Resolvers\IpAddressResolver::class,
        'user_agent' => \OwenIt\Auditing\Resolvers\UserAgentResolver::class,
        'url'        => \OwenIt\Auditing\Resolvers\UrlResolver::class,
        'tenant_id'  => \App\AuditResolvers\TenantResolver::class,
    ],
    'threshold' => 500,
    'queue' => [
        'enable' => true,
        'connection' => 'redis',
        'queue' => 'audits',
        'delay' => 5,
    ],
];
```

--------------------------------

### Read custom resolver output from audit metadata

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

Example of reading the resolved tenant id from the audit metadata array.

```php
$audit->getMetadata()['audit_tenant_id']; // 1
```

--------------------------------

### disableAuditing() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-audit-control.md

Disables auditing for the Article model, creates a record without an Audit, then re-enables auditing.

```php
Article::disableAuditing();

Article::factory()->create(); // saved, but no Audit record is created

Article::enableAuditing();
```

--------------------------------

### Implementing the Auditable contract and using the Auditable trait

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

To make a model auditable, it must use the Auditable trait and implement the AuditableContract. This example shows the required imports, class declaration, trait usage, and fillable attributes.

```php
use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Auditable;
use OwenIt\Auditing\Contracts\Auditable as AuditableContract;

class Article extends Model implements AuditableContract
{
    use Auditable;

    protected $fillable = ['title', 'content', 'reviewed'];
}
```

--------------------------------

### isAuditingDisabled() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-audit-control.md

Checks if auditing is currently disabled for the Article model. If true, auditing is switched off.

```php
if (Article::isAuditingDisabled()) {
    // auditing currently switched off
}
```

--------------------------------

### setAuditEvent() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Sets the audit event to 'created' and checks if the model is ready for auditing. Returns true when 'created' is in audit.events.

```php
$article->setAuditEvent('created');
$article->readyForAuditing(); // true when 'created' is in audit.events
```

--------------------------------

### Define $auditStrict on a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example setting $auditStrict to true, ensuring that hidden/invisible attributes are never audited.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    public $auditStrict = true; // hidden + invisible attributes are never audited
}
```

--------------------------------

### Define $auditThreshold on a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-configuration-getters.md

Example setting $auditThreshold to 100 to keep only the newest 100 audits per model.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    public $auditThreshold = 100; // keep at most 100 audits per article
}
```

--------------------------------

### Catching AuditingException

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/errors.md

Catch any audit processing failure by catching AuditingException. The example logs the exception message when toAudit() throws.

```php
use \OwenIt\Auditing\Exceptions\AuditingException;

try {
    $article->toAudit();
} catch (AuditingException $e) {
    log('audit skipped: ' . $e->getMessage());
}
```

--------------------------------

### AuditDriverCommand for auditing:audit-driver

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

The AuditDriverCommand extends GeneratorCommand to create a new audit driver skeleton from stubs/driver.stub into the {rootNamespace}\AuditDrivers namespace. The example command generates app/AuditDrivers/RedisDriver.php.

```php
class AuditDriverCommand extends GeneratorCommand
{
    protected $name = 'auditing:audit-driver';
    protected $description = 'Create a new audit driver';
    protected $type = 'AuditDriver';

    protected function getStub()
    {
        return __DIR__.'/../../stubs/driver.stub';
    }

    protected function getDefaultNamespace($rootNamespace)
    {
        return $rootNamespace.'\AuditDrivers';
    }
}
```

```bash
php artisan auditing:audit-driver RedisDriver
# creates app/AuditDrivers/RedisDriver.php
```

--------------------------------

### boot() method implementation

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

Boot method that registers publishing, merges config, and conditionally registers event listeners. If audit.enabled is falsy, it returns early, making auditing fully inert.

```php
public function boot()
{
    $this->registerPublishing();
    $this->mergeConfigFrom(__DIR__.'/../config/audit.php', 'audit');

    if (!$this->app->make('config')->get('audit.enabled', true)) {
        return;
    }

    Event::listen(AuditCustom::class, RecordCustomAudit::class);
    Event::listen(DispatchAudit::class, ProcessDispatchAudit::class);
}
```

--------------------------------

### Catching AuditableTransitionException

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/errors.md

Example of catching AuditableTransitionException when calling transitionTo(). The getIncompatibilities() method returns attribute names that caused the failure, such as ['removed_column'] when schema drift is the cause.

```php
use \OwenIt\Auditing\Exceptions\AuditableTransitionException;

try {
    $model->transitionTo($audit);
} catch (AuditableTransitionException $e) {
    $e->getIncompatibilities(); // ['removed_column'] when schema drift caused the failure
}
```

--------------------------------

### Events\AuditCustom

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Event class for recording custom audit events. Can be dispatched from application code to record arbitrary events, and is handled by the RecordCustomAudit listener in a default install.

```APIDOC
## Events\AuditCustom

### Description
Event class for recording custom audit events. Can be dispatched from application code to record arbitrary events, and is handled by the RecordCustomAudit listener in a default install.

### Constructor
- **model** (Auditable) - The auditable model instance.

### Usage Example
```php
use \OwenIt\Auditing\Events\AuditCustom;

$article->auditCustomOld = ['field' => 'old value'];
$article->auditCustomNew = ['field' => 'new value'];
$article->isCustomEvent = true;
$article->auditEvent = 'exported';

Event::dispatch(new AuditCustom($article));
```

### Notes
- Dispatched by `Auditable::dispatchRelationAuditEvent()` (pivot helpers).
- Configurable from application code to record arbitrary custom events.
- Listener `RecordCustomAudit` forwards the model to `Auditor::execute()`.
- Source: `src/Events/AuditCustom.php`
```

--------------------------------

### resolveData() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-trait.md

Finds an audit record, calls resolveData(), and accesses the resolved data keys such as 'audit_event', 'new_title', and 'user_email'.

```php
$audit = Audit::find(1);
$audit->resolveData();
// $audit->data['audit_event'];   // 'created'
// $audit->data['new_title'];     // 'Hello'
// $audit->data['user_email'];    // from the user's arrayable attributes
```

--------------------------------

### Register and select a custom driver

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/drivers.md

Shows how to register the custom driver in boot logic and select it per model via the auditDriver property.

```php
// boot logic
$this->app->extend('auditing.driver', 'metrics', \App\AuditDrivers\MetricsDriver::class);

// model level
public $auditDriver = 'metrics';
```

--------------------------------

### Dispatch AuditCustom event

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Dispatches the AuditCustom event directly from application code. Sets custom old/new values, marks the event as custom, sets the audit event to 'exported', and dispatches the event with the model. In a default install, the RecordCustomAudit listener handles it.

```php
use \OwenIt\Auditing\Events\AuditCustom;

$article->auditCustomOld = ['field' => 'old value'];
$article->auditCustomNew = ['field' => 'new value'];
$article->isCustomEvent = true;
$article->auditEvent = 'exported';

Event::dispatch(new AuditCustom($article));
```

--------------------------------

### audits() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Shows retrieving the latest audit for an article and accessing modified attributes. The audits() relation returns a MorphMany instance.

```php
$article = Article::find(1);
$latestAudit = $article->audits()->latest()->first();

$audit->getModified();       // array of modified attributes
```

--------------------------------

### preloadResolverData()

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Runs all configured resolvers and stores the results in $preloadedResolverData, additionally resolving the user via resolveUser() and storing it under the 'user' key when non-empty. This is what makes queueing correct.

```APIDOC
## preloadResolverData()

### Description
Runs all configured resolvers (see `runResolvers()`) and stores the results in `$preloadedResolverData`, additionally resolving the user via `resolveUser()` and storing it under the `'user'` key when non-empty. Resolvers read this preloaded data instead of re-resolving at audit time, which is what makes queueing (`audit.queue.enable`) correct: the dispatch event is serialized after preloading.

### Method
`preloadResolverData`

### Signature
```php
public function preloadResolverData()
```

### Return
- **$this** - Returns the current instance for chaining

### Throws
- **OwenIt\Auditing\Exceptions\AuditingException** - Invalid resolver or user-resolver configuration (see [errors.md](../errors.md)).

### Example
```php
$article->preloadResolverData();

$article->preloadedResolverData['ip_address']; // cached by IpAddressResolver
$article->preloadedResolverData['user'];       // resolved user (or absent)
```

### Notes
Called automatically by `AuditableObserver::dispatchAudit()` before the audit is executed or queued — application code normally does not need to invoke it.

### Source
`src/Auditable.php:403`
```

--------------------------------

### boot method declaration

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

Declares the boot method of the service provider.

```php
public function boot()
```

--------------------------------

### Setting auditThreshold on a model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/drivers.md

Example model that sets the auditThreshold property to 5, causing the prune method to keep the newest 5 audits and delete older ones.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    public $auditThreshold = 5; // keep newest 5 audits, prune older
}
```

--------------------------------

### auditDetach usage examples

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-pivot-auditing.md

Examples of detaching related models with auditDetach. The first detaches a specific key with touch disabled; the second detaches all rows of the relation.

```php
$detached = $user->auditDetach('groups', [$group->getKey()], touch: false);

// or detach all rows of the relation
$detached = $article->auditDetach('categories');
```

--------------------------------

### Run Migration for Audit Logs Table

Source: https://github.com/owen-it/laravel-auditing/wiki/Getting-Started

Run the migration to create the 'logs' table in your database, which is used to save audit logs.

```bash
php artisan migrate
```

--------------------------------

### Non-trivial usage of transitionTo() in an approval workflow

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-transition.md

Shows an approve() method that finds the creation audit for an article, applies the state captured at creation time via transitionTo(), sets status to 'approved', and saves.

```php
public function approve(Article $article): void
{
    $creationAudit = $article->audits()
        ->where('event', 'created')
        ->firstOrFail();

    // Apply the state captured at creation time
    $article->transitionTo($creationAudit);
    $article->status = 'approved';
    $article->save();
}
```

--------------------------------

### readyForAuditing() method signature

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Declares the readyForAuditing() method that returns a boolean indicating whether the model may produce an audit.

```php
public function readyForAuditing(): bool
```

--------------------------------

### bootAuditable() method signature

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Registers AuditableObserver on the model class. No-op unless App::getFacadeRoot() is truthy and Config::get('audit.enabled', true) is truthy. Returns void.

```php
public static function bootAuditable()
```

--------------------------------

### Basic usage of transitionTo() to revert an article

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-transition.md

Fetches an Article, retrieves its latest audit, and calls transitionTo() with old: true to revert to the previous state, then saves. Catches AuditableTransitionException and retrieves incompatibilities.

```php
$article = Article::find(10);

// Revert the article to its state before the last update
$lastAudit = $article->audits()->latest()->first();

try {
    $article->transitionTo($lastAudit, old: true);
    $article->save();
} catch (\OwenIt\Auditing\Exceptions\AuditableTransitionException $e) {
    // type/id mismatch, redactor configured, or schema incompatibility
    $e->getIncompatibilities(); // e.g. ['deleted_column']
}
```

--------------------------------

### Publish Laravel Auditing Configuration

Source: https://github.com/owen-it/laravel-auditing/wiki/Getting-Started

Publish the configuration settings for Laravel Auditing. Run this after adding the service provider.

```bash
php artisan vendor:publish --provider="OwenIt\Auditing\AuditingServiceProvider"
```

--------------------------------

### Enable Facades and Eloquent in Lumen

Source: https://github.com/owen-it/laravel-auditing/wiki/Getting-Started

Uncomment the withFacades() and withEloquent() calls in Lumen's bootstrap/app.php to enable facades and Eloquent, which are required for Laravel Auditing.

```php
// ...
$app->withFacades();

$app->withEloquent();
// ...
```

--------------------------------

### register() method implementation

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

Registers the three artisan commands and binds the Auditor class as a singleton in the application container.

```php
public function register()
{
    $this->commands([
        AuditDriverCommand::class,
        AuditResolverCommand::class,
        InstallCommand::class,
    ]);

    $this->app->singleton(Auditor::class, function ($app) {
        return new \OwenIt\Auditing\Auditor($app);
    });
}
```

--------------------------------

### getSerializedDate() usage example

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-trait.md

Calls getSerializedDate() with a Carbon date instance, producing a string like '2024-05-01 12:00:00'.

```php
$audit->getSerializedDate($carbonDate); // e.g. '2024-05-01 12:00:00'
```

--------------------------------

### Generate custom resolver with artisan command

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

Command to generate a custom resolver skeleton using the console generator.

```bash
php artisan auditing:audit-resolver TenantResolver
```

--------------------------------

### OwenIt\Auditing\Contracts\Resolver and UserResolver interfaces

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/types.md

Define the contract for resolvers. Resolver is implemented by Resolvers\IpAddressResolver, Resolvers\UserAgentResolver, Resolvers\UrlResolver, and Resolvers\DumpResolver; UserResolver by Resolvers\UserResolver. Referenced by the audit.resolvers config (values must implement Resolver) and the audit.user.resolver config (must implement UserResolver).

```php
interface Resolver
{
    /** @return mixed */
    public static function resolve(Auditable $auditable);
}

interface UserResolver
{
    public static function resolve();
}
```

--------------------------------

### RecordCustomAudit listener

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Listener registered by AuditingServiceProvider::boot() for AuditCustom events. Turns a custom event into a real audit write.

```php
class RecordCustomAudit
{
    public function handle(AuditCustom $event): void
    {
        Auditor::execute($event->model);
    }
}
```

--------------------------------

### bootAuditable() usage in Article model

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Example of overriding bootAuditable() in a model class that uses the Auditable trait. The inherited trait implementation registers AuditableObserver.

```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    // Called once by the framework boot process
    public static function bootAuditable()
    {
        // inherited trait implementation registers AuditableObserver
    }
}
```

--------------------------------

### preloadResolverData() method signature

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Signature of the preloadResolverData() method. It takes no parameters and returns $this. It runs all configured resolvers and stores results for later use.

```php
public function preloadResolverData()
```

--------------------------------

### OwenIt\Auditing\Contracts\AuditDriver interface

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/types.md

Defines the contract for audit drivers. Implemented by OwenIt\Auditing\Drivers\Database by default; custom drivers can be created via the auditing:audit-driver command using the stub stubs/driver.stub. Returned by Auditor::auditDriver().

```php
interface AuditDriver
{
    public function audit(Auditable $model): ?Audit;
    public function prune(Auditable $model): bool;
}
```

--------------------------------

### createDatabaseDriver() method signature

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditor.md

Protected method that creates and returns a Database driver instance. Returns OwenIt\Auditing\Drivers\Database.

```php
protected function createDatabaseDriver(): Database
```

--------------------------------

### getTable() method signature

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-trait.md

Returns the table name for the audit model. The return value is config('audit.drivers.database.table', parent::getTable()), falling back to the parent model's table (default 'audits').

```php
public function getTable(): string
```

--------------------------------

### dispatchAudit() method signature

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-observer.md

Shared pipeline entry: returns when the model is not ready for auditing or auditing is disabled, preloads resolver data, and either executes the auditor directly or dispatches a queued audit event.

```php
protected function dispatchAudit(Auditable $model): void
```

--------------------------------

### LeftRedactor usage in attributeModifiers

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/attribute-modifiers.md

Example configuration mapping the 'iban' attribute to LeftRedactor. The comment shows that 'DE89370400' (10 chars) becomes '#########0', with the rightmost ~10% visible.

```php
public $attributeModifiers = [
    'iban' => \OwenIt\Auditing\Redactors\LeftRedactor::class,
];

// 'DE89370400' (10 chars) → '#########0' — rightmost ~10% stays visible
```

--------------------------------

### Audit queue configuration

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Configuration for the audit queue. Enables queueing, sets the connection to 'sync', the queue to 'default', and the delay to 0.

```php
// audit.php
'queue' => [
    'enable' => true,
    'connection' => 'sync',
    'queue' => 'default',
    'delay' => 0,
],
```

--------------------------------

### readyForAuditing()

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Determines whether the model may produce an Audit right now. Returns `false` when auditing is disabled, `true` for custom events, otherwise whether the current audit event is an auditable event.

```APIDOC
## readyForAuditing()

### Description
Determines whether the model may produce an Audit right now. Returns `false` when auditing is disabled (`isAuditingDisabled()`), `true` for custom events (`$isCustomEvent === true`), otherwise whether the current `auditEvent` is an auditable event.

### Method
`readyForAuditing(): bool`

### Return
- `bool` — `true` if the model is ready to produce an audit, `false` otherwise.

### Example
```php
if (! $article->readyForAuditing()) {
    return; // skip — auditing disabled or event not configured
}
```
```

--------------------------------

### Event flow summary

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/events-listeners.md

Flow diagram showing the event flow from Eloquent event to audit execution, with branches for queue disabled and queue enabled.

```text
Eloquent event ─▶ AuditableObserver::dispatchAudit()
   ├─ queue disabled ─▶ Auditor::execute()
   │                     ├─ Events\Auditing (veto-able)
   │                     ├─ driver->audit()
   │                     ├─ driver->prune()
   │                     └─ Events\Audited
   └─ queue enabled  ─▶ Events\DispatchingAudit (veto-able)
                        ─▶ Events\DispatchAudit (queued)
                            ─▶ ProcessDispatchAudit::handle()
                               ─▶ Auditor::execute()
```

--------------------------------

### transitionTo(Contracts\Audit $audit, bool $old = false): Contracts\Auditable

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable-transition.md

Moves an Auditable model to the state described by an existing Audit record. For every modified attribute recorded on the audit, the corresponding attribute of the model is set from the audit's old (when $old = true) or new (default) value. The audit must reference this exact model type and key, and the audited attributes must be a subset of the model's current attributes.

```APIDOC
## transitionTo(Contracts\Audit $audit, bool $old = false): Contracts\Auditable

### Description
Moves an Auditable model to the state described by an existing Audit record. For every modified attribute recorded on the audit, the corresponding attribute of the model is set from the audit's old (when $old = true) or new (default) value. The audit must reference this exact model type and key, and the audited attributes must be a subset of the model's current attributes.

### Method
PHP method

### Signature
php
public function transitionTo(Contracts\Audit $audit, bool $old = false): Contracts\Auditable


### Parameters
- **$audit** (Contracts\Audit) - Required - The Audit to transition from
- **$old** (bool) - Optional, default false - Use old values (revert); false applies new values

### Return
- **$this** (Contracts\Auditable) - The model with attributes updated in memory. The caller is responsible for persisting (save()) afterwards.

### Throws
- **AuditableTransitionException** - If $audit->auditable_type differs from $this->getMorphClass() — "Expected Auditable type %s, got %s instead"
- **AuditableTransitionException** - If $audit->auditable_id differs from $this->getKey() — "Expected Auditable id (%s)%s, got (%s)%s instead"
- **AuditableTransitionException** - If any configured attributeModifiers entry is a subclass of AttributeRedactor — "Cannot transition states when an AttributeRedactor is set" (redacted data must never be written back)
- **AuditableTransitionException** - If any modified attribute of $audit is not a key of $this->getAttributes() — "Incompatibility between [%s:%s] and [%s:%s]", carrying the list of incompatible attribute names (see getIncompatibilities())

### Basic Usage Example
php
$article = Article::find(10);

// Revert the article to its state before the last update
$lastAudit = $article->audits()->latest()->first();

try {
    $article->transitionTo($lastAudit, old: true);
    $article->save();
} catch (\OwenIt\Auditing\Exceptions\AuditableTransitionException $e) {
    // type/id mismatch, redactor configured, or schema incompatibility
    $e->getIncompatibilities(); // e.g. ['deleted_column']
}


### Non-trivial Usage Example — Audit-driven approval workflow
php
public function approve(Article $article): void
{
    $creationAudit = $article->audits()
        ->where('event', 'created')
        ->firstOrFail();

    // Apply the state captured at creation time
    $article->transitionTo($creationAudit);
    $article->status = 'approved';
    $article->save();
}


### Behavioral Notes
- The model type check compares morph classes: $this->getMorphClass() !== $audit->auditable_type.
- The id check compares keys strictly: $this->getKey() !== $audit->auditable_id.
- Modified attributes come from $audit->getModified(), whose shape is ['attribute' => ['old' => value, 'new' => value]].
- Only the requested side is applied per attribute: setAttribute($attribute, $value[$key]) where $key is 'old' or 'new'.
- Incompatibilities are computed as array_diff_key($modified, $this->getAttributes()) and can be retrieved via AuditableTransitionException::getIncompatibilities().
```

--------------------------------

### RightRedactor usage in attributeModifiers

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/attribute-modifiers.md

Example configuration mapping 'email' and 'password' attributes to RightRedactor. The comment shows that 'john@ex.co' (10 chars) becomes 'j#########', with the leftmost ~10% visible.

```php
public $attributeModifiers = [
    'email'    => \OwenIt\Auditing\Redactors\RightRedactor::class,
    'password' => \OwenIt\Auditing\Redactors\RightRedactor::class,
];

// 'john@ex.co' (10 chars) → 'j#########' — leftmost ~10% stays visible
```

--------------------------------

### OwenIt\Auditing\Contracts\Audit interface

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/types.md

Defines the contract for audit records. Implemented by OwenIt\Auditing\Models\Audit via the OwenIt\Auditing\Audit trait, with replacements configurable via audit.implementation. Produced by Drivers\Database::audit() and Events\Audited::$audit, and consumed by Auditable::transitionTo().

```php
interface Audit
{
    public function getConnectionName();
    public function getTable();
    public function auditable();
    public function user();
    public function resolveData(): array;
    public function getDataValue(string $key);
    public function getMetadata(bool $json = false, int $options = 0, int $depth = 512);
    public function getModified(bool $json = false, int $options = 0, int $depth = 512);
}
```

--------------------------------

### Configure audit.php to skip empty audits

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditor.md

Sets 'empty_values' to false to skip audits with empty values, and allows 'retrieved' events explicitly since they are always empty.

```php
// In audit.php config
'empty_values' => false,
// 'retrieved' events are always empty, so allow them explicitly
'allowed_empty_values' => ['retrieved'],
```

--------------------------------

### DumpResolver class implementation

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

A no-op resolver that returns an empty string. Useful as a template or placeholder; empty implementations are skipped by runResolvers() when configured with an empty value.

```php
class DumpResolver implements Resolver
{
    public static function resolve(Auditable $auditable): string
    {
        return '';
    }
}
```

--------------------------------

### AuditResolverCommand class for generating audit resolvers

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/service-provider-console.md

Defines the artisan command 'auditing:audit-resolver' that generates a new resolver skeleton implementing Contracts\Resolver into the {rootNamespace}\AuditResolvers namespace. The handle() method prints a reminder to register the resolver in the audit.php config file before delegating to the parent GeneratorCommand.

```php
class AuditResolverCommand extends GeneratorCommand
{
    protected $name = 'auditing:audit-resolver';
    protected $description = 'Create a new audit resolver';
    protected $type = 'AuditResolver';

    protected function getStub()
    {
        return __DIR__.'/../../stubs/resolver.stub';
    }

    protected function getDefaultNamespace($rootNamespace)
    {
        return $rootNamespace.'\AuditResolvers';
    }

    public function handle()
    {
        $this->info('Add your new resolver to the resolvers array in audit.php config file.');

        return parent::handle();
    }
}
```

--------------------------------

### Register custom resolver in audit.php config

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/resolvers.md

Configuration array showing how to register the custom resolver under the 'resolvers' key, alongside stock resolvers.

```php
// audit.php
'resolvers' => [
    'ip_address' => \OwenIt\Auditing\Resolvers\IpAddressResolver::class,
    'user_agent' => \OwenIt\Auditing\Resolvers\UserAgentResolver::class,
    'url'        => \OwenIt\Auditing\Resolvers\UrlResolver::class,
    'tenant_id'  => \App\AuditResolvers\TenantResolver::class,
],
```

--------------------------------

### OwenIt\Auditing\Contracts\Auditor interface

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/types.md

Defines the contract for the auditor service. Implemented by OwenIt\Auditing\Auditor, which is registered as an application singleton and accessed via the OwenIt\Auditing\Facades\Auditor static facade.

```php
interface Auditor
{
    public function auditDriver(Auditable $model): AuditDriver;
    public function execute(Auditable $model);
}
```

--------------------------------

### bootAuditable()

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/auditable.md

Registers the AuditableObserver on the model class so Eloquent lifecycle events are forwarded to the auditing pipeline. It is a static method called once by the framework boot process.

```APIDOC
## `bootAuditable()` — static

### Description
Registers `AuditableObserver` on the model class so Eloquent lifecycle events are forwarded to the auditing pipeline.

### Method
`bootAuditable()`

### Return
`void`

### Conditions
- No-op unless `App::getFacadeRoot()` is truthy and `Config::get('audit.enabled', true)` is truthy.

### Source
`src/Auditable.php:78`

### Example
```php
class Article extends Model implements AuditableContract
{
    use Auditable;

    // Called once by the framework boot process
    public static function bootAuditable()
    {
        // inherited trait implementation registers AuditableObserver
    }
}
```
```

--------------------------------

### Generate a custom audit driver skeleton

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/drivers.md

Console command to generate a skeleton custom audit driver named MetricsDriver.

```bash
php artisan auditing:audit-driver MetricsDriver
```

--------------------------------

### Generated custom driver skeleton

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/drivers.md

Generated skeleton for a custom audit driver, with TODO comments for implementing audit and prune logic.

```php
class MetricsDriver implements \OwenIt\Auditing\Contracts\AuditDriver
{
    public function audit(Auditable $model): Audit
    {
        // TODO: Implement the audit logic
    }

    public function prune(Auditable $model): bool
    {
        // TODO: Implement the pruning logic
    }
}
```

--------------------------------

### Controller usage with audit data accessors

Source: https://github.com/owen-it/laravel-auditing/blob/master/_autodocs/api-reference/audit-data-access.md

Shows how to retrieve an audit by ID and pass metadata, modified values, and tags to a view. Uses Audit::findOrFail and the getMetadata(), getModified(), and getTags() methods.

```php
public function show(int $auditId)
{
    $audit = Audit::findOrFail($auditId);

    return view('audits.show', [
        'metadata' => $audit->getMetadata(),
        'modified' => $audit->getModified(),
        'tags'     => $audit->getTags(),
    ]);
}
```

--------------------------------

### Register AuditingServiceProvider in Lumen

Source: https://github.com/owen-it/laravel-auditing/wiki/Getting-Started

Register the AuditingServiceProvider in Lumen's bootstrap/app.php. This step is required.

```php
$app->register(OwenIt\Auditing\AuditingServiceProvider::class);
```
Tokens:
Raw