README

jeylabs/laravel-audit-log 包提供了一个易于使用的函数来记录您的应用程序用户的操作。它还可以自动记录模型事件。所有活动都将存储在 audit_logs 表中。

auditLog()->log('Look, I logged something');

您可以使用 Jeylabs\Auditlog\Models\AuditLog 模型检索所有活动。

AuditLog::all();

这是一个更高级的示例

auditLog()
   ->performedOn($anEloquentModel)
   ->causedBy($user)
   ->withProperties(['customProperty' => 'customValue'])
   ->log('Look, I logged something');
   
$lastLoggedAudit = AuditLog::all()->last();

$lastLoggedAudit->subject; //returns an instance of an eloquent model
$lastLoggedAudit->causer; //returns an instance of your user model
$lastLoggedAudit->getExtraProperty('customProperty'); //returns 'customValue'
$lastLoggedAudit->description; //returns 'Look, I logged something'

$newsItem->name = 'updated name';
$newsItem->save();

//updating the newsItem will cause an activity being logged
$auditLog = AuditLog::all()->last();

$auditLog->description; //returns 'updated'
$auditLog->subject; //returns the instance of NewsItem that was created

调用 $auditLog->changes 将返回此数组

[
   'attributes' => [
        'name' => 'updated name',
        'text' => 'New Text',
    ],
    'old' => [
        'name' => 'original name',
        'text' => 'Old text',
    ],
];

安装

您可以通过 composer 安装此包

composer require jeylabs/laravel-audit-log

接下来，您必须安装服务提供者

// config/app.php
'providers' => [
    ...
    Jeylabs\AuditLog\AuditLogServiceProvider::class,
];

您可以使用以下命令发布迁移

php artisan vendor:publish --provider="Jeylabs\AuditLog\AuditLogServiceProvider" --tag="migrations"

注意：默认迁移假设您正在使用整数作为您的模型 ID。如果您使用 UUID 或其他格式，请在继续之前调整已发布的迁移中 subject_id 和 causer_id 字段的格式。

迁移发布后，您可以通过运行迁移来创建 audit-logs 表

php artisan migrate

您可以选择使用以下命令发布配置文件

php artisan vendor:publish --provider="Jeylabs\AuditLog\AuditLogServiceProvider" --tag="config"

这是已发布配置文件的内容

return [
    /**
     * You can specify the route prefix
     */
    'route_prefix' => 'audit-log',
    /**
     * When user visit every url update audit log
     */
    'record_visiting' => false,

    /*
     * If set to false, no audits will be saved to the database.
     */
    'enabled' => env('AUDIT_LOGGER_ENABLED', true),

    /*
     * When the clean-command is executed, all recording audits older than
     * the number of days specified here will be deleted.
     */
    'delete_records_older_than_days' => 365,

    /*
     * If no log name is passed to the audit() helper
     * we use this default log name.
     */
    'default_log_name' => 'default',

    /*
     * You can specify an auth driver here that gets user models.
     * If this is null we'll use the default Laravel auth driver.
     */
    'default_auth_driver' => null,

    /*
     * If set to true, the subject returns soft deleted models.
     */
    'subject_returns_soft_deleted_models' => false,

    /*
     * This model will be used to log audit. The only requirement is that
     * it should be or extend the \Jeylabs\AuditLog\Models\AuditLog model.
     */
    'audit_log_model' => \Jeylabs\AuditLog\Models\AuditLog::class,
    
    /*
     * If set to true, it will store lat/long to the database
     */
    'track_location' => true,

    /*
     * If set to true, it will store ip address to the database
     */
    'track_ip' => true,
];

记录模型事件

此包的一个巧妙功能是它可以自动记录事件，例如当模型被创建、更新和删除。要使此功能正常工作，您只需让您的模型使用 Jeylabs\AuditLog\Traits\LogsAudit-trait。

作为奖励，当在模型上设置 $logAttributes 属性时，该包还将记录所有这些事件的更改属性。

以下是一个示例

use Illuminate\Database\Eloquent\Model;
use Jeylabs\AuditLog\Traits\LogsAudit

class NewsItem extends Model
{
    use LogsAudit;

    protected $fillable = ['name', 'text'];
    
    protected static $logAttributes = ['name', 'text'];
}

让我们看看创建该模型实例时记录了什么。

$newsItem = NewsItem::create([
   'name' => 'original name',
   'text' => 'New Text'
]);

//creating the newsItem will cause an activity being logged
$auditLog = AuditLog::all()->last();

$auditLog->description; //returns 'created'
$auditLog->subject; //returns the instance of NewsItem that was created
$auditLog->changes; //returns ['attributes' => ['name' => 'original name', 'text' => 'Text']];

现在让我们更新一些 $newsItem。

$newsItem->name = 'updated name'
$newsItem->save();

//updating the newsItem will cause an activity being logged
$auditLog = AuditLog::all()->last();

$auditLog->description; //returns 'updated'
$auditLog->subject; //returns the instance of NewsItem that was created

调用 $auditLog->changes 将返回此数组

[
   'attributes' => [
        'name' => 'updated name',
        'text' => 'New text',
    ],
    'old' => [
        'name' => 'original name',
        'text' => 'Old text',
    ],
];

现在，调用删除时会发生什么？

$newsItem->delete();

//deleting the newsItem will cause an activity being logged
$auditLog = AuditLog::all()->last();

$auditLog->description; //returns 'deleted'
$auditLog->changes; //returns ['attributes' => ['name' => 'updated name', 'text' => 'Text']];

自定义要记录的事件

默认情况下，该包将记录 created、updated、deleted 事件。您可以通过设置模型上的 $recordEvents 属性来修改此行为。

use Illuminate\Database\Eloquent\Model;
use Jeylabs\AuditLog\Traits\CausesAudit;

class NewsItem extends Model
{
    use CausesAudit;

    //only the `deleted` event will get logged automatically
    protected static $recordEvents = ['deleted'];
}

自定义描述

默认情况下，该包将在活动的描述中记录 created、updated、deleted。您可以通过重写 getDescriptionForEvent 函数来修改此文本。

use Illuminate\Database\Eloquent\Model;
use Jeylabs\AuditLog\Traits\CausesAudit;

class NewsItem extends Model
{
    use CausesAudit;

    protected $fillable = ['name', 'text'];

    public function getDescriptionForEvent(string $eventName): string
    {
        return "This model has been {$eventName}";
    }

}

现在让我们看看会发生什么

$newsItem = NewsItem::create([
   'name' => 'original name',
   'text' => 'original Text'
]);

//creating the newsItem will cause an activity being logged
$auditLog = AuditLog::all()->last();

$auditLog->description; //returns 'This model has been created'

忽略某些属性的更改

如果您的模型包含某些属性的更改不需要触发活动记录，您可以使用 $ignoreChangedAttributes

use Illuminate\Database\Eloquent\Model;
use Jeylabs\AuditLog\Traits\LogsAudit;

class NewsItem extends Model
{
    use LogsAudit;
    
    protected static $ignoreChangedAttributes = ['text'];

    protected $fillable = ['name', 'text'];
    
    protected static $logAttributes = ['name', 'text'];
}

更改 text 不会触发审计记录。

默认情况下，updated_at 属性不被忽略，并且将触发活动记录。您可以将 updated_at 属性添加到 $ignoreChangedAttributes 数组中，以覆盖此行为。

仅记录更改的属性

如果您不想在 $logAttributes 变量中记录每个属性，但只想记录更新后实际更改的属性，您可以使用 $logOnlyDirty

use Illuminate\Database\Eloquent\Model;
use Jeylabs\AuditLog\Traits\LogsAudit;

class NewsItem extends Model
{
    use LogsAudit;

    protected $fillable = ['name', 'text'];
    
    protected static $logAttributes = ['name', 'text'];
    
    protected static $logOnlyDirty = true;
}

仅更改 name 意味着只有 name 属性将在活动中记录，而 text 将被省略。

使用 CausesAudit 特性

该包附带一个 CausesAudit 特性，可以添加到任何用作因果模型的模型。它提供了一个 auditLog 关系，它返回由模型引起的所有活动。

如果您将其包含在 User 模型中，您可以简单地像这样检索所有当前用户的操作

\Auth::user()->auditLog;

jeylabs / laravel-audit-log

维护者

详细信息