README

一个轻量级包，提供快速轻松审计 Laravel 应用程序中发生的事件和操作的能力。

安装

您可以通过 composer 安装此包

composer require motomedialab/simple-laravel-audit

完成此操作后，运行您的迁移。这将创建一个名为 audit_logs 的表。

php artisan migrate

配置

默认情况下，不需要配置此包。它将与默认设置一起工作。

但是，如果您想自定义任何选项，例如表名或使用的类，您可以发布配置文件并更改任何选项。它设计得非常灵活，允许您更改 IP 地址解析、用户 ID 解析、表名等。

php artisan vendor:publish --tag=simple-auditor

为合规性隐藏 IP 地址

您可以通过将 .env 文件中的 SIMPLE_AUDITOR_OBFUSCATE_IP 变量设置为 true 来轻松隐藏提交到数据库的 IP 地址。这将删除 IP 地址的前两个八位字节，确保它符合各种合规性法律，如 GDPR。幕后，这会将默认的 IP 地址检索器切换为隐藏的 IP 地址检索器。

设置保留期限

您可以通过在 .env 文件中设置 SIMPLE_AUDITOR_RETENTION 来定义您的日志应保留多少天。如果您想无限期保留所有日志，请将其设置为 0。

SIMPLE_AUDITOR_RETENTION=30 # retain for 30 days
SIMPLE_AUDITOR_RETENTION=0 # retain indefinitely

每次审计日志被修剪时，这将记录为审计日志本身。

用法

您可以使用多种方式使用此包。最常见的方式是使用 audit 辅助函数。

使用全局审计助手

audit 辅助函数是一种快速将日志记录到审计表的方法。此函数的第一个参数是字符串，第二个参数是可选的数组（上下文）。这仅适用于您尚未拥有名为 audit 的全局函数。

audit('Action performed', ['more_data' => 'Goes here']);

使用外观

一些人喜欢使用 Laravel 的外观，因为它们易于使用且具有静态特性。

// import the facade
use Motomedialab\SimpleLaravelAudit\Facades\AuditFacade;

// create our audit log
AuditFacade::audit('Action performed', ['more_data' => 'Goes here']);

绑定到事件

如果您想审计应用程序中发生的事件，可以使用 IsAuditableEvent 接口。结合 AuditableEvent，这将自动将事件记录到审计日志。

以下是一个使用 IsAuditableEvent 接口的事件示例

// import our contract & trait
use Motomedialab\SimpleLaravelAudit\Contracts\IsAuditableEvent;
use Motomedialab\SimpleLaravelAudit\Traits\AuditableEvent;

class MyCustomEvent implements IsAuditableEvent
{
    use AuditableEvent;

    public function handle()
    {
        // ToDo: your event logic.
    }
    
    // optional - by default will be handled by the AuditableEvent trait
    public function getAuditMessage(): string
    {
        return 'Action performed';
    }
    
    // optional - by default will be handled by the AuditableEvent trait
    public function getAuditContext(): array
    {
        return ['more_data' => 'Goes here'];
    }
}

在模型上使用 AuditableModel 特性

如果您有一个希望在更改时进行审计的模型，可以使用 AuditableModel 特性。默认情况下，这将为此模型的所有创建、更新和删除记录到审计日志。这使用 Laravel 模型观察器来监听更改。默认情况下，排除 created_at 和 updated_at 列从审计。

use Illuminate\Database\Eloquent\Model;
use Motomedialab\SimpleLaravelAudit\Traits\AuditableModel;

class YourModel extends Model
{
    use AuditableModel;
    
    /**
    * An array of columns that shouldn't be audited.
    * @var array|string[] 
    */
    protected array $excludedFromAuditing = [
        'created_at',
        'updated_at',
    ];
}

自定义 AuditableModel 功能

如果您想扩展 AuditableModel 特性的功能，可以通过在配置文件中配置 observer 键来覆盖其观察器。这将允许您创建自己的模型观察器。

use Motomedialab\SimpleLaravelAudit\Observers\AuditableModelObserver as BaseObserver;

class AuditableObserver extends BaseObserver
{
    // your custom classes here
    // see https://laravel.net.cn/docs/11.x/eloquent#observers for more information
}

贡献

有关详细信息，请参阅 CONTRIBUTING

安全

如果您发现任何安全问题，请通过电子邮件 chris@motocom.co.uk 而不是使用问题跟踪器。

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件