Version

WARNING You're browsing the documentation for an upcoming version of Laravel Auditable. The documentation and features of this release are subject to change.

Auditable Trait

Using AuditableTrait on your model provides the following API for accessing audit information.

Boot

The trait automatically registers an observer when your model is booted:

public static function bootAuditableTrait(): void

This method is called automatically when the trait is used on a model and sets up the AuditableTraitObserver to handle audit field updates.

Creator

Get the instance of the user who created the record:

public function creator(): BelongsTo

Example:

$post = Post::first();
$creator = $post->creator;
 
echo $creator->name; // "John Doe"

Updater

Get the instance of the user who last updated the record:

public function updater(): BelongsTo

Example:

$post = Post::first();
$updater = $post->updater;
 
echo $updater->name; // "Jane Smith"

deleter

Get the instance of the user who deleted the record. This requires using AuditableWithDeletesTrait instead:

public function deleter(): BelongsTo

Example:

$post = Post::withTrashed()->first();
$deleter = $post->deleter;
 
echo $deleter->name; // "Admin User"

::: tip Related Documentation For tracking who deleted records, see Soft Deletes Auditable for setup and usage instructions. :::

createdByName Attribute

Get the full name of the user who created the record:

public function getCreatedByNameAttribute(): string

Example:

$post = Post::first();
echo $post->created_by_name; // "John Doe"

updatedByName Attribute

Get the full name of the user who last updated the record:

public function getUpdatedByNameAttribute(): string

Example:

$post = Post::first();
echo $post->updated_by_name; // "Jane Smith"

deletedByName Attribute

Get the full name of the user who deleted the record. This requires AuditableWithDeletesTrait:

public function getDeletedByNameAttribute(): string

Example:

$post = Post::withTrashed()->first();
echo $post->deleted_by_name; // "Admin User"

scopeOwned

A query scope that limits results to records owned by the current authenticated user. This filters records where created_by matches the current user's ID:

public function scopeOwned(Builder $query): Builder

Example:

auth()->loginUsingId(1);
 
$posts = Post::owned()->get();
 
// Equivalent SQL:
// SELECT * FROM posts WHERE posts.created_by = 1

::: tip When to Use scopeOwned Use this scope to implement record ownership, filtering queries to show only records created by the authenticated user. :::

getQualifiedUserIdColumn

Get the fully qualified column name for the created_by field:

public function getQualifiedUserIdColumn(): string

Example:

$post = new Post();
echo $post->getQualifiedUserIdColumn(); // "posts.created_by"
// or "posts.author_id" if CREATED_BY constant is defined

getUserInstance

Get an instance of the configured user class:

public function getUserInstance(): Model

Example:

$post = new Post();
$user = $post->getUserInstance();
// Returns a new instance of the configured user model

getUserClass

Get the user class name, respecting any auditUser property override:

protected function getUserClass(): string

Example:

$post = new Post();
echo $post->getUserClass(); // "App\Models\User"
// or "App\Models\Admin" if $auditUser is set

getCreatedByColumn

Get the column name for the created by field:

public function getCreatedByColumn(): string

Example:

$post = new Post();
echo $post->getCreatedByColumn(); // "created_by"
// or "author_id" if CREATED_BY constant is defined

getUpdatedByColumn

Get the column name for the updated by field:

public function getUpdatedByColumn(): string

Example:

$post = new Post();
echo $post->getUpdatedByColumn(); // "updated_by"
// or "last_editor_id" if UPDATED_BY constant is defined

getDeletedByColumn

Get the column name for the deleted by field. This requires AuditableWithDeletesTrait:

public function getDeletedByColumn(): string

Example:

$post = new Post();
echo $post->getDeletedByColumn(); // "deleted_by"

Edit this page on GitHub