README

• 首先将包添加到您的项目中

  composer require corb/logging

• 在您的config/app.php文件中添加服务提供者

  Corb\Logging\LoggingServiceProvider::class

• 发布包文件

  php artisan vendor:publish --provider="Corb\Logging\LoggingServiceProvider"

  这将在您的config/目录中添加一个配置文件，名为logging.php。所有必需的迁移也将复制到您的迁移文件夹中。

  您还可以使用config和migrations标签单独发布这些文件

  php artisan vendor:publish --tag=config --provider="Corb\Logging\LoggingServiceProvider"

  php artisan vendor:publish --tag=migrations --provider="Corb\Logging\LoggingServiceProvider"

日志记录

在此处使用的日志记录概念是记录应用程序中发生的特定事件或主要是操作。有关这些操作的一些信息也被注册，通常是执行操作的谁，执行操作的何时，以及该操作的主题；例如：“Matilda（谁）在2016年17/13日（何时）发明了一个新的月份（主题）”。所有这些信息都存储在activity_logs表中，可以使用ActivityLog模型进行查询。

由于创建新日志有一些复杂性，例如多态关系，因此Loggeable特性和Logger类提供了一个简单的接口来执行此操作。

日志上下文

对于某些操作，除了上述一般信息外，还有一些我们可能希望存储的上下文数据。例如，更新事件注册了更新模型实例的之前和之后状态。由于这些上下文数据仅用于特定操作，因此它们不存储在activity_logs表中，而是在自己的表中存储。必须为每个具有上下文数据的操作创建一个表。对于更新事件，这些数据存储在update_log_contexts表中。这样，如果您想为自定义操作存储额外数据，则需要创建其自己的上下文表。有一些实用程序可以方便地包含自定义操作，有关如何操作的更多信息，请参阅日志记录自定义操作。

配置

config/logging.php文件定义了一些选项，您可以更改这些选项以满足您的需求。

user_model

指示您的应用程序的用户模型。此模型在创建新日志时用作责任人。

'user_model' => 'App\User'

auth_method

此方法应返回您应用程序中的当前认证用户。它用于在记录操作时自动设置责任人ID，如果未提供责任人ID，则将启用此功能。

'auth_method' => '\Auth::user'

上下文

定义应用程序中可用的 日志上下文 的数组。每个元素将定义与 Corb\Logging\Models\ActivityLog 模型的一对一关系。键表示关系的名称，值是关系指向的模型。这样，您可以使用此属性访问每条日志中的上下文，并在查询多个日志时预加载上下文。

'contexts' => [
    'update_context' => 'Corb\Logging\Models\UpdateLogContext'
]

动作

在配置文件的顶部，有一个抽象类 Actions，其中定义了所有可记录的动作作为常量成员。您可以在其中添加自己的动作或更改预定义动作键。

abstract class Actions
{
    const CREATE = 'create';
    const UPDATE = 'update';
    const DELETE = 'delete';
}

可记录

Corb\Logging\Traits\Loggeable 特性允许使用它的模型在 activity_logs 表中注册新条目。

use Illuminate\Database\Eloquent\Model;
use Corb\Logging\Traits\Loggeable;

class MyLoggeableModel extends Model
{
    use Loggeable;
    ...
}

您可以使用 createLog 方法在模型上记录动作

createLog

public function createLog($action, $context = NULL, $responsible_id = NULL)

$action

$action 是一个字符串，用于标识执行的操作。它可以是你想要的任何字符串，但应尽可能简单，例如：'update'。默认动作已注册为常量，位于 config/logging.php 文件下的 Corb\Logging\Actions 类中。您应该考虑在这里注册自己的动作，这样就可以通过使用 Actions::MY_ACTION 来创建和查询日志，从而防止出现任何错误。

$context

指代 日志上下文。它应该是使用 Corb\Logging\Traits\LogContext 的模型实例。如果没有提供，则不会与日志关联任何上下文。

$responsible_id

表示执行动作的用户 ID。如果为 NULL，则假定当前记录的用户为责任人。

示例

您可以通过以下方式在模型上简单地记录一个动作

// Within your loggeable model
$this->createLog('my_action');

// On a loggeable model instance
$loggeable->createLog('my_action');

有关创建具有上下文的日志的示例，请参阅 记录自定义动作。

模型的日志事件

默认情况下，当使用此特性时，您的模型的 created、updated 和 deleted 事件将被记录。如果只想记录某些或这些事件中的任何一个，您可以在模型中设置 log_events 数组属性，指定必须记录哪些事件。

例如，如果您想记录 created 和 updated 事件，但不记录 deleted 事件，则可以使用

use Illuminate\Database\Eloquent\Model;
use Corb\Logging\Traits\Loggeable;

class MyLoggeableModel extends Model
{
    use Loggeable;

    // Which of the 'created', 'updated' and 'deleted' events should be logged
    protected $log_events = ['created', 'updated'];
    ...
}

这可以用于各种场景，例如，您需要定义自己的 update 事件逻辑时。

您可能已经注意到，在 Actions 类 中定义的默认动作与这些事件相对应：CREATE、UPDATE 和 DELETE 常量的值分别在记录 created、updated 和 deleted 事件时用作动作。

更新事件

更新事件日志还存储在由 Corb\Logging\Models\UpdateLogContext 模型使用的 update_log_contexts 表中。这些数据包括两个字段：before 和 after。这两个都是序列化对象，包含已更新的属性。before 包含原始值，而 after 存储更新后的值。

查询您的模型日志

要查询您的模型日志，您应该使用 activityLogs 动态属性。它定义了可记录模型与 Corb\Logging\Models\ActivityLog 模型之间的 一对多 关系，因此可以用作查询构建器。

您可以通过以下方式检索模型的全部 updated 事件日志

use Corb\Logging\Actions;
...
$loggeable = MyLoggeableModel::first();

$updates = $loggeable->activityLogs()->where('action', Actions::UPDATE)->get();

如果您记得，更新事件有一些上下文数据，您可以在 update_context 动态属性下检索这些数据。

$first_update = $updates->first()->update_context;

$first_update->update_context->before;
$first_update->update_context->after;

update_context 属性定义了 Corb\Logging\Models\ActivityLog 模型和 Corb\Logging\Models\UpdateLogContext 模型之间的关系。update_context 属性是“懒加载”的，这意味着只有在访问该属性时才会执行检索相应 update_log_contexts 记录所需的查询。这可能会造成问题，因为您将为每条日志执行额外的查询。您可以通过 预加载 您的日志上下文来防止这种情况。

预加载日志上下文

您应该使用 with 方法一次性加载所有日志上下文。

$loggeable->activityLogs()->with('update_context')->where('action', Actions::UPDATE);

现在您可以在不执行额外查询的情况下访问 update_context 属性。

记录器

Corb\Logging\Logger 类定义了一个简单的 create 方法来记录新的日志。建议与 Loggeable 特性中的 createLog 方法一起使用此方法，而不是直接使用 ActivityLog 模型创建日志，因为这些方法解决了日志、上下文日志和可记录实例之间的关系。

create

public static function create($action, $context = NULL, $responsible_id = NULL, $loggeable = NULL)

$action, $context, $responsible_id

$action、$context 和 $responsible_id 参数与 createLog 方法中的参数具有相同的作用。

$loggeable

表示执行动作的模型。该模型预期将使用 Corb\Logging\Traits\Loggeable 特性。

此方法的目的是在创建新的日志条目时提供最大的灵活性，因此您可以使用模型创建带有或没有模型的日志，尽管这不被推荐。

示例

use Corb\Logging\Logger;
...
Logger::create('my_action');

ActivityLog

App\Models\ActivityLog 模型抽象了 activity_logs 表。在 Loggeable 特性中，activityLogs 属性返回的是此模型的实例。这些实例包含每条日志的通用信息。

$log = $loggeable->activityLogs()->first()

$log->action      // the logged action
$log->responsible // user responsible for the action
$log->created_at  // log creation date
$log->loggeable   // the entity on which the action was perfomed

用户活动

您可以访问您的历史活动记录，即所有用户作为责任人的日志。为此，请将 Corb\Logging\Traits\UserActivity 特性添加到您的用户模型中。

use Illuminate\Foundation\Auth\User as Authenticatable;
use Corb\Logging\Traits\UserActivity;

class User extends Authenticatable
{
    use UserActivity;

    ...

这将向您的模型添加一个 activity 方法，该方法定义了一个与 ActivityLog 模型的 HasMany 关系，因此您可以查询用户活动。

$user = User::first();

$activity = $user->activity()->orderBy('created_at', 'desc')->get();

记录自定义操作

我们已经看到，您可以通过在创建日志时简单地使用一个标识它的字符串来记录任何想要的动作。我们还提到，您可以在 app/loggin.php 中定义的 Actions 类中正确地定义这些动作。真正的问题是，当您需要存储动作日志的 上下文数据 时。如前所述，您需要将此数据存储在其自己的表中，此外，您还需要为该表创建一个模型并在配置文件的 contexts 数组中注册它。按照以下步骤正确定义要记录的新动作。

定义新动作

首先，我们需要注册新动作。转到 app\logging.php 文件，并将您的动作作为 Actions 抽象类中的 const 成员添加。

...
abstract class Actions
{
    const UPDATE = 'update';
    const CREATE = 'create';
    const DELETE = 'delete';
    ...
    const MY_ACTION = 'my_action';
}

上下文表迁移

现在，如果您想存储动作日志的上下文数据，为您的上下文表创建一个新的迁移。上下文表所需唯一列是一个外键 activity_log_id，它将引用 activity_logs 表上属于该日志的字段。

    Schema::create('my_action_log_contexts', function (Blueprint $table) {
        $table->increments('id');

        // context data
        $table->text('data');
        ...

        // add foreign key
        $table->integer('activity_log_id')->unsigned();
        $table->foreign('activity_log_id')->references('id')->on('activity_logs')
              ->onDelete('cascade');
    });
    ...

日志上下文模型

接下来，为您 上下文表 创建一个模型。确保将 Corb\Logging\Traits\LogContext 特性添加到您的模型中。

namespace MyApp\Models\MyActionLogContext;

use Illuminate\Database\Eloquent\Model;
use Corb\Logging\Traits\LogContext;

class MyActionLogContext extends Model
{
    use LogContext;

    protected $table = 'my_action_log_contexts';
    ...

启用预加载

为了允许 预加载 您的日志上下文，您必须将其添加到 app/logging.php 配置文件中的 context 数组中。

    ...

    'contexts' => [
        'update_context'    => 'Corb\Logging\Models\UpdateLogContext',
        'my_action_context' => 'MyApp\Models\MyActionLogContext'
    ]

使用它

现在您可以创建操作日志并查询它们

// Create a context instance
$context = new MyActionLogContext();

// Fill your context with the necessary data
$context->data = $data

// Log your action
$loggeable->createLog(Actions::MY_ACTION, $context);

//Query your logs
$log = $loggeable->activityLogs()->with('my_action_context')->where('action', Actions::MY_ACTION')->first();

$log->my_action_context->data;
$log->responsible;
...