README

此 Doctrine 2 扩展受到 Hibernate Envers 的启发，允许对实体及其关联进行完整版本控制。

支持

有关一般支持和问题，请使用 StackOverflow。

如果您认为您发现了一个错误或您有要提出的功能想法，请自由地打开一个问题， 在查看 贡献指南 之后。

许可

此包可在 LGPL 许可证 下使用。

它是如何工作的？

数据库表审计或版本控制有多种不同的方法。此扩展为每个审计的实体表创建一个镜像表，后缀为 "_audit"。除了审计实体的所有列外，还有两个字段

• rev - 包含从 "revisions" 表生成的全局修订号。
• revtype - 包含 'INS'、'UPD' 或 'DEL' 之一，作为数据库操作类型引起此修订日志条目的信息。

全局修订表包含 id、时间戳、用户名和变更注释字段。

使用这种方法，可以在特定时间点对应用程序及其对关联的更改进行版本控制。

此扩展挂钩到 SchemaTool 生成过程，以便它将自动为您审计的实体创建必要的 DDL 语句。

安装

安装包

简单地运行，假设您有 composer

$ composer require sonata-project/entity-audit-bundle

启用包

最后，在内核中启用包

// config/bundles.php

return [
    //...
    SimpleThings\EntityAudit\SimpleThingsEntityAuditBundle::class => ['all' => true],
    //...
];

配置

加载扩展 "simple_things_entity_audit" 并指定要审计的实体

# config/packages/entity_audit.yaml

simple_things_entity_audit:
    audited_entities:
        - MyBundle\Entity\MyEntity
        - MyBundle\Entity\MyEntity2

如果您需要排除某些实体属性以触发修订，请使用

# config/packages/entity_audit.yaml

simple_things_entity_audit:
    global_ignore_columns:
        - created_at
        - updated_at

为了与其他连接或实体管理器 "default" 一起工作，请使用以下设置

# config/packages/entity_audit.yaml

simple_things_entity_audit:
    connection: custom
    entity_manager: custom

如果您需要显式排除从审计实体推断的外键，可以使用 disable_foreign_keys 参数

simple_things_entity_audit:
    disable_foreign_keys: true

创建新表

调用以下命令以查看更新模式队列中的新表。

./bin/console doctrine:schema:update --dump-sql

独立安装

对于独立使用，您必须将待审计的实体类名称传递给 MetadataFactory 实例并配置两个事件监听器。

use Doctrine\ORM\Configuration;
use Doctrine\ORM\EntityManager;
use Doctrine\Common\EventManager;
use SimpleThings\EntityAudit\AuditConfiguration;
use SimpleThings\EntityAudit\AuditManager;
use SimpleThings\EntityAudit\Tests\ArticleAudit;
use SimpleThings\EntityAudit\Tests\UserAudit;

$auditConfig = new AuditConfiguration();
$auditConfig->setAuditedEntityClasses([ArticleAudit::class, UserAudit::class]);
$auditConfig->setGlobalIgnoreColumns(['created_at', 'updated_at']);

$eventManager = new EventManager();
$auditManager = new AuditManager($auditConfig);
$auditManager->registerEvents($eventManager);

$config = new Configuration();
// $config ...
$connection = [];
$entityManager = EntityManager::create($connection, $config, $eventManager);

用法

使用 SimpleThings\EntityAudit\AuditReader 实例查询审计信息。

use SimpleThings\EntityAudit\AuditReader;

class DefaultController extends Controller
{
    public function indexAction(AuditReader $auditReader)
    {
    }
}

在独立应用程序中，您可以从审计管理器创建审计读取器

$auditReader = $auditManager->createAuditReader($entityManager);

查找特定修订的实体状态

此命令还会返回给定修订的实体状态，即使对该实体的最后一次更改是在给定修订之前进行的

$articleAudit = $auditReader->find(
    SimpleThings\EntityAudit\Tests\ArticleAudit::class,
    $id = 1,
    $rev = 10
);

通过 AuditReader#find() 创建的实例 不会 注入到 EntityManagers UnitOfWork 中，如果需要将它们重新附加到旧版本的持久上下文，它们需要合并到 EntityManager 中。

查找审计实体的修订历史

$revisions = $auditReader->findRevisions(
    SimpleThings\EntityAudit\Tests\ArticleAudit::class,
    $id = 1
);

修订有以下的API

class Revision
{
    public function getRev();
    public function getTimestamp();
    public function getUsername();
}

在特定修订中查找已更改的实体

$changedEntities = $auditReader->findEntitiesChangedAtRevision(10);

已更改的实体有以下的API

class ChangedEntity
{
    public function getClassName();
    public function getId();
    public function getRevisionType();
    public function getEntity();
}

查找审计实体的当前修订

$revision = $auditReader->getCurrentRevision(
    'SimpleThings\EntityAudit\Tests\ArticleAudit',
    $id = 3
);

设置当前用户名

每个修订都会自动保存更改它的用户名。为了使其工作，用户名必须被解析。

在Symfony网络上下文中，用户名是从当前安全上下文令牌中解析出来的。

您可以通过在包配置中配置username_callable服务来覆盖此功能。您的自定义服务必须是一个callable，应该返回一个string或null。

# config/packages/entity_audit.yaml

simple_things_entity_audit:
    service:
        username_callable: acme.username_callable

在独立应用程序或Symfony命令中，您可以使用AuditConfiguration将用户名可调用设置为特定值。

$auditConfig = new \SimpleThings\EntityAudit\AuditConfiguration();
$auditConfig->setUsernameCallable(function () {
	$username = //your customer logic
    return username;
});

查看审计

提供了一个默认的Symfony控制器，它提供了查看审计数据的基线功能。

要使用此控制器，导入路由（别忘了确保您设置的地址前缀安全，以确保只有适当的用户可以访问）

# config/routes.yaml

simple_things_entity_audit:
    resource: "@SimpleThingsEntityAuditBundle/Resources/config/routing/audit.xml"
    prefix: /audit

这为您提供了几个不同的路由

• simple_things_entity_audit_home - 显示修订的分页列表，它们的时间戳以及执行修订的用户
• simple_things_entity_audit_viewrevision - 显示特定修订中修改的类
• simple_things_entity_audit_viewentity - 显示指定实体被修改的修订
• simple_things_entity_audit_viewentity_detail - 显示指定修订中指定实体的数据
• simple_things_entity_audit_compare - 允许您比较两个修订之间实体的更改

待办事项

• 目前仅适用于自增数据库
• 需要适当的元数据映射，允许禁用字段和关联的版本控制。
• 它不与联合表继承（单表继承应该工作，但未测试）兼容