README

⚠️ 免责声明

此包仍在开发中，可能会频繁更改。

简介

此包允许创建模型的快照。

虽然当需要模型版本控制时，添加版本列的典型方法通常足够，但此包在专用表中存储快照。这提供了更好的快照控制，并保持您的表整洁。

创建此包的动机是在需要时仅创建可配置的快照，而不是在每次更新时都生成新的版本，同时保持与最新原始模型的连接。

安装

您可以通过 composer 安装此包

composer require eribloo/laravel-model-snapshots

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

php artisan vendor:publish --tag="model-snapshots-migrations"
php artisan migrate

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

php artisan vendor:publish --tag="model-snapshots-config"

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

return [

    /**
     * Snapshot class used. Must implement EriBloo\LaravelModelSnapshots\Contracts\Snapshot interface.
     */
    'snapshot_class' => EriBloo\LaravelModelSnapshots\Models\Snapshot::class,

    /**
     * Versionist class used. Must implement EriBloo\LaravelModelSnapshots\Contracts\Versionist interface.
     */
    'versionist_class' => EriBloo\LaravelModelSnapshots\Support\Versionists\IncrementingVersionist::class,

];

用法

基础

创建快照

您可以使用辅助函数 snapshot() 创建快照

snapshot(Document::find(1))->commit();

这将使用在 EriBloo\LaravelModelSnapshots\SnapshotOptions 类中定义的默认选项来创建模型的快照

使用配置中定义的版本主义者类设置版本
快照所有属性，排除主键、时间戳和隐藏属性
如果已存在具有相同存储属性的另一个快照，则不会创建快照 - 在这种情况下，将返回匹配的快照

每个快照存储一个包含模型属性、创建时使用的选项、版本和可选描述的数组。

快照提供了 toModel(bool $fillExcludedAttributes = false) 方法，该方法返回填充了快照属性的模型。如果可选的 fillExcludedAttributes 选项为 true，返回的模型将使用当前模型属性作为基础，否则缺失的属性将为 null。

相应地，如果您检索到快照集合，您可以使用其 toModels(bool $fillExcludedAttributes = false) 方法将所有快照映射到相应的类。

回滚、分支和分支快照

快照有 3 个辅助方法来从快照恢复模型或创建新的模型

revert() - 将原始模型恢复到其快照版本，删除使用后创建的所有快照
branch() - 从快照版本创建新模型，并复制到包含和包括所使用的一个快照的所有快照，将它们关联到新模型
fork() - 从快照版本创建新模型，没有快照历史记录

排除在快照之外将使用当前模型值填充属性。

关系

此外，包提供了一个单独的表来存储与其它模型的快照关系。有 morphToMany 和 morphToOne 关系可用，它们在 HasSnapshotRelations 特质中返回 Snapshots 或 Models。

配置

快照选项

可以通过在模型上创建 getSnapshotOptions() 方法来定义选项

public function getSnapshotOptions(): SnapshotOptions
{
    return SnapshotOptions::defaults();
}

可配置的选项包括

withVersionist(Versionist $versionist) - 设置版本主义者
snapshotExcept(array $exclude) - 排除要存储的属性
snapshotHidden(bool $option = true) - 存储隐藏属性
snapshotDuplicate(bool $option = true) - 强制创建快照，即使已存在相同的快照

大多数方法都可以在快照时通过这些方法进行覆盖

version(Closure $closure) - 接收当前 Versionist 对象的闭包，这样您可以在需要时访问和调用其方法
description(?string) - 添加可选的简短描述
setExcept(array $except)、appendExcept(array $except)、removeExcept(array $except) - 修改排除属性列表
withHidden()、withoutHidden() - 修改是否应该快照隐藏属性
forceDuplicate()、noDuplicate() - 即使已存在重复的快照，也要强制创建快照

版本主义者

Versionist 是一个负责确定下一个快照版本的类。默认情况下有 2 个类可用

IncrementingVersionist - 增量版本
SemanticVersionist - 以 major.minor 格式保留版本

如果您想创建自己的版本类，它必须实现 EriBloo\LaravelModelSnapshots\Contracts\Versionist 并具有方法

public function getFirstVersion(): string;

public function getNextVersion(string $version): string;

特质

虽然创建快照不需要特性，但此包提供了 2 个辅助特性来检索快照

HasSnapshots - 提供了 snapshots() 关系以检索存储的快照以及一些获取器
- getLatestSnapshot()
- getSnapshotByVersion(string $version) - 返回指定版本的快照
- getSnapshotByDate(DateTimeImmutable $date) - 返回在指定日期之前创建的最后一个快照
HasSnapshotRelations - 提供创建与快照连接的关系方法
- morphSnapshots(string $snapshotClass) - 辅助 morphToMany
- morphSnapshot(string $snapshotClass) - 辅助 morphToOne
- morphSnapshotAsModels(string $snapshotClass) - 返回具有 toModels(false) 应用的快照的 morphToMany
- morphSnapshotAsModel(string $snapshotClass) - 返回具有 toModel(false) 应用的快照的 morphToOne

事件

有一些事件被触发

SnapshotCommitted - 在提交新快照时触发，但在找到重复时不会触发
SnapshotReverted - 在回滚快照时触发
SnapshotBranched - 在创建新快照分支时触发
SnapshotForked - 在快照被分叉时触发

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志

许可证

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

eribloo / laravel-model-snapshots

维护者

详情