README

如果能在项目中为任何模型保留修订历史，而不需要做任何工作，那不是很好吗。只需将RevisionableTrait特质添加到您的模型中，您就可以立即做到这一点，并能显示类似以下的历史记录

Chris将标题从'Something'改为'Something else'
Chris将类别从'News'改为'Breaking news'
Matt将类别从'Breaking news'改为'News'

因此，您不仅可以看到发生了什么，还可以看到是谁做了什么，因此有责任。

Revisionable是一个Laravel包，允许您无需思考即可为模型保留修订历史。有关背景信息，请参阅这篇文章

与第三方Auth / Eloquent扩展一起工作

Revisionable支持由以下Auth提供的功能

(推荐)Revisionable现在也可以作为特质使用，因此您的模型可以继续扩展Eloquent，或任何扩展Eloquent的其他类（如Ardent）。

安装

Revisionable可以通过composer进行安装，详细信息请参阅packagist，此处。

将以下内容添加到项目的composer.json文件的require部分

"venturecraft/revisionable": "1.*",

运行composer update以下载包

php composer.phar update

打开config/app.php并注册所需的服务提供程序（Laravel 5.x）

'providers' => [
	Venturecraft\Revisionable\RevisionableServiceProvider::class,
]

发布配置和迁移（Laravel 5.x）

php artisan vendor:publish --provider="Venturecraft\Revisionable\RevisionableServiceProvider"

最后，您还需要在包上运行迁移（Laravel 5.x）

php artisan migrate

Laravel 4.x用户

php artisan migrate --package=venturecraft/revisionable

如果您经常完全迁移上下文（使用migrate:refresh），您可以这样做：将包中的迁移文件从app/database文件夹复制到您的迁移文件中，并将类名从CreateRevisionsTable更改为类似于CreateRevisionTable的内容（不带's'，否则您将收到重复类的错误）

cp vendor/venturecraft/revisionable/src/migrations/2013_04_09_062329_create_revisions_table.php database/migrations/

实现

基于特质的新实现（推荐）

特质需要PHP >= 5.4

对于您想要保留修订历史记录的任何模型，请包含VentureCraft\Revisionable命名空间并在您的模型中使用RevisionableTrait，例如：

namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    use RevisionableTrait;
}

作为一个特质，Revisionable现在可以与标准Eloquent模型或任何扩展Eloquent的类（如Ardent）一起使用。

基于旧类的方法

新的基于特质的方法与Revisionable的现有安装向后兼容。您仍然可以使用以下安装说明，这本质上是一个为特质扩展的包装器。

对于您想要保留修订历史记录的任何模型，请包含VentureCraft\Revisionable命名空间并在您的模型中使用RevisionableTrait，例如：

use Venturecraft\Revisionable\Revisionable;

namespace App;

class Article extends Revisionable { }

注意：这也适用于命名空间模型。

实现说明

如有需要，您可以通过在模型中将 $revisionEnabled 设置为 false 来禁用版本控制。这可能在您想暂时禁用版本控制或创建一个扩展自 Revisionable 的基础模型时很有用，其中所有模型都扩展了这个模型，但您希望某些模型关闭 Revisionable。

namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    protected $revisionEnabled = false;
}

您还可以通过将 $historyLimit 设置为您希望停止版本控制的修订次数之前要保留的修订次数来在完成 X 次修订后禁用版本控制。

namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    protected $revisionEnabled = true;
    protected $historyLimit = 500; //Stop tracking revisions after 500 changes have been made.
}

为了限制历史记录，但如果您想要删除旧修订，而不是停止跟踪修订，可以通过设置 $revisionCleanup 来实现该功能。

namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    protected $revisionEnabled = true;
    protected $revisionCleanup = true; //Remove old revisions (works only when used with $historyLimit)
    protected $historyLimit = 500; //Maintain a maximum of 500 changes at any point of time, while cleaning up old revisions.
}

存储软删除

默认情况下，如果您的模型支持软删除，Revisionable 将将此存储并任何恢复都视为模型上的更新。

您可以通过将 deleted_at 添加到 $dontKeepRevisionOf 数组中来选择忽略删除和恢复。

为了更好地格式化 deleted_at 条目的输出，您可以使用 isEmpty 格式化器（有关示例，请参阅格式化输出）。

存储创建

默认情况下，创建新模型不会被存储为修订。只有对模型的后续更改才会被存储。

如果您想将创建存储为修订，可以通过将 revisionCreationsEnabled 设置为 true 并添加以下内容到模型中来自定义此行为：

protected $revisionCreationsEnabled = true;

格式输出

您可以使用 Eloquent 访问器 在模型中设置值的输出（有关访问器的更多信息，请参阅 Laravel 文档）。以下文档已弃用

在您想要控制值输出格式的情况下，例如布尔字段，您可以在模型中设置它们为 $revisionFormattedFields 数组。例如：

protected $revisionFormattedFields = [
    'title'      => 'string:<strong>%s</strong>',
    'public'     => 'boolean:No|Yes',
    'modified'   => 'datetime:m/d/Y g:i A',
    'deleted_at' => 'isEmpty:Active|Deleted'
];

您还可以使用模型中的 $revisionFormattedFieldNames 数组覆盖字段名称输出，例如：

protected $revisionFormattedFieldNames = [
    'title'      => 'Title',
    'small_name' => 'Nickname',
    'deleted_at' => 'Deleted At'
];

这将在您使用 $revision->fieldName() 输出修订字段名称时发挥作用。

字符串

要格式化字符串，只需在值前加上 string: 并确保包括 %s（这是实际值将在格式化响应中出现的部分），例如：

string:<strong>%s</strong>

布尔值

布尔值默认将显示为 0 或 1，这相当单调，对最终用户没有太多意义，因此可以使用此格式化器输出更友好的内容。在值前加上 boolean: 并然后添加您的 false 和 true 选项，用竖线分隔，例如：

boolean:No|Yes

选项

类似于 "布尔值"，任何文本或数值都可以作为源值（通常标志存储在数据库中）。该格式允许您根据值指定不同的输出。将其视为关联数组，其中键与值由点分隔。数组元素由竖线分隔。

options: search.On the search|network.In networks

日期时间

日期时间默认将显示为 Y-m-d H:i:s。在值前加上 datetime: 并然后添加您的日期时间格式，例如：

datetime:m/d/Y g:i A

是否为空

这是基于布尔值的，但检查的不是布尔值，而是值是否为 null 或空字符串。

isEmpty:No|Yes

这也可以接受 %s，如果您想输出值，以下示例将显示 '无' 如果值是空的，或者如果存在实际值则显示实际值。

isEmpty:Nothing|%s

加载修订历史

要加载给定模型的修订历史，只需在该模型上调用 revisionHistory 方法，例如：

$article = Article::find($id);
$history = $article->revisionHistory;

显示历史记录

在大多数情况下，修订历史将包含足够的信息以直接输出变更历史，但在外键更新时，我们需要进行一些映射并显示比 plan_id 从 3 更改为 1 更好的内容。

为此，有几个辅助方法可以显示更多有见解的信息，因此您可以显示类似 Chris 将计划从青铜改为黄金 的内容。

上述内容将是以下结果

@foreach($account->revisionHistory as $history )
    <li>{{ $history->userResponsible()->first_name }} changed {{ $history->fieldName() }} from {{ $history->oldValue() }} to {{ $history->newValue() }}</li>
@endforeach

如果您已启用创建的修订，您还可以这样显示：

@foreach($resource->revisionHistory as $history)
  @if($history->key == 'created_at' && !$history->old_value)
    <li>{{ $history->userResponsible()->first_name }} created this resource at {{ $history->newValue() }}</li>
  @else
    <li>{{ $history->userResponsible()->first_name }} changed {{ $history->fieldName() }} from {{ $history->oldValue() }} to {{ $history->newValue() }}</li>
  @endif
@endforeach

userResponsible()

返回负责进行修订的用户。返回用户模型，如果没有记录用户则返回 null。

加载的用户模型取决于您在 config/auth.php 文件中为 model 变量设置的值。

fieldName()

返回更新的字段的名称。如果更新的字段是外键（在此阶段，它只是查看字段是否有 _id 后缀），则返回 _id 前面的文本。例如，如果字段是 plan_id，则返回 plan。

记住，您可以在模型中通过覆盖 $revisionFormattedFieldNames 数组来更改字段的输出。

identifiableName()

当值（旧值或新值）是外键关系的 ID 时使用。

默认情况下，它简单地返回更新的模型的 ID。您可以在自己的模型中覆盖此方法以返回有意义的值。例如：

use Venturecraft\Revisionable\Revisionable;

class Article extends Revisionable
{
    public function identifiableName()
    {
        return $this->title;
    }
}

oldValue() 和 newValue()

获取模型更新前或更新后的值。如果是外键，则调用 identifiableName()。

未知或无效的外键作为修订

在旧值或新值是不再存在的外键或实际上是 null 的情况下，您可以在模型中设置两个变量来控制这些情况下的输出。

protected $revisionNullString = 'nothing';
protected $revisionUnknownString = 'unknown';

disableRevisionField()

有时暂时禁用一个可修订的字段可能会有所帮助，如果您想保存更新但不需要记录更改。

$object->disableRevisionField('title'); // Disables title

或

$object->disableRevisionField(['title', 'content']); // Disables title and content

贡献

欢迎和鼓励贡献；为了保持有序，所有错误和请求都应该在主项目的 GitHub 问题标签页中打开，在 venturecraft/revisionable/issues

所有拉取请求都应提交到 develop 分支，以便在合并到 master 分支之前进行测试。

遇到麻烦了吗？

如果您在使用此包时遇到问题，那么其他人可能已经遇到过相同的问题。您可以在以下两个地方查找常见问题的答案：

如果您更愿意在 StackOverflow 上公开提问，请使用 'revisionable' 标签。

alscheuring / revisionable

维护者

详细信息