README

此包为所有Doctrine ORM数据库相关变更创建审计日志，包括它们的差异和关联字段差异。

• 插入和更新，以及它们的差异和关联字段差异。
• 多对多关系变更，关联和解除关联操作。
• 如果令牌存储中有用户，则用于标识进行了更改的用户。
• 审计条目将在flush期间插入到同一事务中，如果出现错误，状态保持清洁。

基本上，如果您通过标准ORM操作管理这些日志条目，您就可以跟踪任何变更。

注意：审计无法跟踪DQL或直接SQL更新或删除语句的执行。

此包受data-dog/audit-bundle和simplethings/entity-audit-bundle的启发。

安装

使用Symfony Flex的应用程序

打开命令行，进入您的项目目录并执行以下命令

composer require damienharper/doctrine-audit-bundle

未使用Symfony Flex的应用程序

步骤1：下载包

打开命令行，进入您的项目目录，并执行以下命令以下载此包的最新稳定版本

composer require damienharper/doctrine-audit-bundle

此命令要求您全局安装Composer，如Composer文档中的安装章节所述。

步骤2：启用包

然后，通过将其添加到项目app/AppKernel.php文件中注册的包列表来启用包。

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new DH\DoctrineAuditBundle\DHDoctrineAuditBundle(),
        );

        // ...
    }

    // ...
}

配置

被审计的实体和属性

默认情况下，DoctrineAuditBundle不会审计任何实体，您必须配置哪些实体需要被审计。

// app/config/config.yml (symfony < 3.4)
// config/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    entities:
        MyBundle\Entity\MyAuditedEntity1: ~
        MyBundle\Entity\MyAuditedEntity2: ~

所有MyAuditedEntity1和MyAuditedEntity2属性都将被审计。尽管可以排除其中的一些属性不进行审计。

// app/config/config.yml (symfony < 3.4)
// config/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    entities:
        MyBundle\Entity\MyAuditedEntity1: ~   # all MyAuditedEntity1 properties are audited
        MyBundle\Entity\MyAuditedEntity2:
            ignored_columns:                  # properties ignored by the audit process
                - createdAt
                - updatedAt

还可以指定审计过程中全局忽略的属性。

// app/config/config.yml (symfony < 3.4)
// config/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    ignored_columns:    # properties ignored by the audit process in any audited entity
        - createdAt
        - updatedAt

审计表命名格式

审计表名称由前缀、被审计的表名称和后缀组成。默认情况下，前缀为空，后缀为_audit。尽管，它们可以进行自定义。

// app/config/config.yml (symfony < 3.4)
// config/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    table_prefix: ''
    table_suffix: '_audit'

创建审计表

打开命令行，进入您的项目目录，并执行以下命令以审查更新模式队列中的新审计表。

# symfony < 3.4
app/console doctrine:schema:update --dump-sql 

# symfony >= 3.4
bin/console doctrine:schema:update --dump-sql 

注意：DoctrineAuditBundle当前仅与名为“default”的DBAL连接和EntityManager一起使用。

使用Doctrine Migrations Bundle

# symfony < 3.4
app/console doctrine:migrations:diff
app/console doctrine:migrations:migrate

# symfony >= 3.4
bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

使用Doctrine模式

# symfony < 3.4
app/console doctrine:schema:update --force

# symfony >= 3.4
bin/console doctrine:schema:update --force

审计查看器

将以下路由添加到路由配置中，以启用包含的审计查看器。

// app/config/routing.yml (symfony < 3.4)
// config/routes.yaml (symfony >= 3.4)
dh_doctrine_audit:
    resource: "@DHDoctrineAuditBundle/Controller/"
    type: annotation

可以通过在获取结果之前调用AuditReader::filterBy方法来根据事件类型过滤结果。

    /**
     * @Route("/audit/details/{entity}/{id}", name="dh_doctrine_audit_show_audit_entry", methods={"GET"})
     */
    public function showAuditEntryAction(string $entity, int $id)
    {
        $reader = $this->container->get('dh_doctrine_audit.reader');
        
        $data = $reader
             ->filterBy(AuditReader::UPDATE)   // add this to only get `update` entries.
             ->getAudit($entity, $id)
         ;

        return $this->render('@DHDoctrineAudit/Audit/entity_audit_details.html.twig', [
            'entity' => $entity,
            'entry' => $data[0],
        ]);
    }

可用的常量有

    AuditReader::UPDATE
    AuditReader::ASSOCIATE
    AuditReader::DISSOCIATE
    AuditReader::INSERT
    AuditReader::REMOVE

自定义用户提供者

如果您不使用Symfony的TokenStorage来保存当前用户，您可以配置自定义用户提供者。您只需实现UserProviderInterface并将其配置为名为dh_doctrine_audit.user_provider的服务。

use DH\DoctrineAuditBundle\User\User;
use DH\DoctrineAuditBundle\User\UserInterface;
use DH\DoctrineAuditBundle\User\UserProviderInterface;

class CustomUserProvider implements UserProviderInterface
{
    public function getUser(): ?UserInterface
    {
        // Your logic goes here...
        return new User($yourUserId, $yourUsername);
    }
}

然后在您的services.yaml文件中添加以下内容

services:
    dh_doctrine_audit.user_provider:
        class: App\CustomUserProvider

用法

当您运行架构更新或类似操作时，审核实体将自动映射。此后，所有数据库更改都将反映在审核日志中。

审核清理

注意：需要symfony/lock，安装它请使用composer require symfony/lock

DoctrineAuditBundle提供了一个方便的命令，帮助您清理审核表。打开命令行，进入您的项目目录并执行

# symfony < 3.4
app/console audit:clean

# symfony >= 3.4
bin/console audit:clean

默认情况下，它会清理超过12个月的审核条目。您可以通过提供要保留在审核表中的月份数量来覆盖此设置。例如，要保留18个月

# symfony < 3.4
app/console audit:clean 18

# symfony >= 3.4
bin/console audit:clean 18

如果您计划将其安排为计划任务（例如cron），也可以跳过确认并使命令非交互式

# symfony < 3.4
app/console audit:clean --no-confirm

# symfony >= 3.4
bin/console audit:clean --no-confirm

常见问题解答

我在配置文件中添加了一个新实体，但它没有被审核。

首先检查其命名空间，然后清除您的缓存并重新运行doctrine:schema:update或doctrine:migrations:migrate。

我不使用Symfony的TokenStorage来管理我的用户，我该如何操作？

检查自定义用户提供者部分。

许可证

DoctrineAuditBundle可以免费使用，并受MIT许可证许可。