包简介

A simple way to log changes that occur on Eloquent models

README 文档

README

This solution is simple to integrate and introduces minimal changes to your project: 1 migration, 1 model, 1 trait, and 1 facade.

Installation

Install the package via composer:

composer require elaborate-code/laravel-eloquent-logs

Publish the migrations:

php artisan vendor:publish --tag="eloquent-logs-migrations"

Run the migrations:

php artisan migrate

Publishing config file [Optional]

You can publish the config file with:

php artisan vendor:publish --tag="eloquent-logs-config"

This is the contents of the published config file:

return [
    'logs_model' => \ElaborateCode\EloquentLogs\Models\EloquentLog::class,
    'logs_table' => 'eloquent_logs',

    'user' => \App\Models\User::class,
];

That allows you to rename the logs_table before running the migrations.

Usage

Pick an Eloquent model that you want to log the changes that happen to it and add the HasLogs trait to it.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class ExampleModel extends Model
{
    use \ElaborateCode\EloquentLogs\Concerns\HasLogs;
    // ...
}

After adding that trait, every change made to the model will be recorded.

Important warning from Laravel docs

When issuing a mass update or delete query via Eloquent, the saved, updated, deleting, and deleted model events will not be dispatched for the affected models. This is because the models are never actually retrieved when performing mass updates or deletes.

Retrieving logs

You can load a model's logs using the eloquentLogs relationship:

$example_model->eloquentLogs;

$example_model->load('eloquentLogs');

App\Models\ExampleModel::with('eloquentLogs')->find($id);

And you can query logs directly:

// latest 5 logs with affected models
ElaborateCode\EloquentLogs\Models\EloquentLog::with('loggable')->latest()->limit(5)->get()

Grouping queries

By default each one model event will result in a query to log the action.

$example_model = ExampleModel::create(['name' => 'foo']);

$example_model->update(['name' => 'bar']);

$example_model->delete();

// ⚠️ This will result in 3 queries to insert the 3 events logs into the database

You can improve the logging process by using the CacheEloquentLogQueries facade

use ElaborateCode\EloquentLogs\Facades\CacheEloquentLogQueries;

CacheEloquentLogQueries::start();

$example_model = ExampleModel::create(['name' => 'foo']);

$example_model->update(['name' => 'bar']);

$example_model->delete();

CacheEloquentLogQueries::execute();

// 👍 This will result in 1 query to insert the 3 events logs into the database

The facade includes other methods that you wouldn't necessarily need to use:

// Stops caching and empties the cache without queries execution
CacheEloquentLogQueries::reset();

// Empties the cache but doesn't stop caching
CacheEloquentLogQueries::flushQueries();

// Stops caching until the reuse of start() and doesn't empty the cache
CacheEloquentLogQueries::suspend();

// Returns a boolean
CacheEloquentLogQueries::isCaching();

Ignoring events

You can specify the events to not log on the model instances by listing the events to ignore on YourModel::$loggableOptions['ignore'].

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class ExampleModel extends Model
{
    use \ElaborateCode\EloquentLogs\Concerns\HasLogs;

    public static array $loggableOptions = [
        'ignore' => ['created', 'updated', 'deleted', 'softDeleted', 'forceDeleted', 'restored'],
    ];
    // ...
}

Muting Eloquent events [Laravel stuff]

From seeders:

namespace Database\Seeders;

use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    use WithoutModelEvents; // Add this trait

    public function run(): void
    {
        // Silent eloquent queries ...
    }
}

Anywhere from your code:

\Illuminate\Database\Eloquent\Model::unsetEventDispatcher();

// Silent eloquent queries ...

\Illuminate\Database\Eloquent\Model::setEventDispatcher(app(Dispatcher::class));
// ...