README

您是否希望为项目中的任何模型都保留修订历史，而不必为此做任何工作。通过简单地将修订版扩展到您的模型中，您就可以立即做到这一点，并能够显示类似这样的历史记录

• Chris将标题从'某物'更改为'另一物'
• Chris将类别从'新闻'更改为'重大新闻'
• Matt将类别从'重大新闻'更改为'新闻'

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

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

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

修订版支持由Auth提供的功能

• Cartalyst的Sentry.
• Cartalyst的Sentinel.

修订版现在也可以作为一个特性使用，因此您的模型可以继续扩展Eloquent，或任何扩展Eloquent的类（例如Ardent）。

安装

修订版可以通过composer安装，详细信息请参阅packagist，此处。

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

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

运行composer update以下载包

php composer.phar update

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

php artisan migrate --path=vendor/venturecraft/revisionable/src/migrations

对于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 app/database/migrations/

文档

• 实现
• 更多控制
• 格式输出
• 加载修订历史
• 显示历史
• 贡献
• 遇到麻烦了吗？

实现

新的基于特性的实现

对于您希望保留修订历史记录的任何模型，请包含修订版命名空间并在您的模型中使用RevisionableTrait，例如，如果您正在使用另一个可启动的特性，请确保在模型中重写boot方法；

namespace MyApp\Models;

class Article extends Eloquent {
    use \Venturecraft\Revisionable\RevisionableTrait;

    public static function boot()
    {
        parent::boot();
    }
}

作为一个特性，现在 revisionable 可以与标准的 Eloquent 模型一起使用，或者任何扩展 Eloquent 的类，例如 Ardent。

特性需要 PHP >= 5.4

基于类的旧实现

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

对于任何想要保留修订历史记录的模型，包含 revisionable 命名空间并扩展 revisionable 而不是 eloquent，例如

use Venturecraft\Revisionable\Revisionable;

namespace MyApp\Models;

class Article extends Revisionable { }

请注意，它也适用于命名空间模型。

实现说明

如果需要，您可以在模型中将 $revisionEnabled 设置为 false 以禁用修订。如果您想暂时禁用修订，或者您想创建一个扩展 revisionable 的基础模型，所有模型都扩展这个模型，但您想对某些模型禁用 revisionable，这将很有用。

namespace MyApp\Models;

class Article extends Eloquent {
    use Venturecraft\Revisionable\RevisionableTrait;

    protected $revisionEnabled = false;
}

您还可以通过将 $historyLimit 设置为停止修订之前的修订数来在 X 次修订后禁用修订。

namespace MyApp\Models;

class Article extends Eloquent {
    use Venturecraft\Revisionable\RevisionableTrait;

    protected $revisionEnabled = true;
    protected $historyLimit = 500; //Stop tracking revisions after 500 changes have been made.
}

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

namespace MyApp\Models;

class Article extends Eloquent {
    use Venturecraft\Revisionable\RevisionableTrait;

    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;

更多控制

无疑，有些情况下您只想为模型的部分字段存储修订历史，这支持两种不同的方式。在您的模型中，您可以选择显式指定您想要跟踪的字段，所有其他字段都将被忽略

protected $keepRevisionOf = array(
    'title'
);

或者，您可以选择显式指定您不想跟踪的字段。所有其他字段都将被跟踪。

protected $dontKeepRevisionOf = array(
    'category_id'
);

$keepRevisionOf 设置优先于 $dontKeepRevisionOf

事件

每次创建模型修订时都会触发一个事件。您可以监听 revisionable.created，
revisionable.saved 或 revisionable.deleted。

// app/Providers/EventServiceProviders.php
public function boot(DispatcherContract $events)
{
    parent::boot($events);

    $events->listen('revisionable.*', function($model, $revisions) {
        // Do something with the revisions or the changed model. 
        dd($model, $revisions);
    });
}

格式输出

您可以继续使用（并鼓励使用）模型中的 eloquent 访问器 来设置值的输出，请参阅 Laravel 文档以获取有关访问器的更多信息。以下文档已被弃用。

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

protected $revisionFormattedFields = array(
    '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 = array(
    '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

日期时间

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

datetime:m/d/Y g:i A

是否为空

这依赖于布尔值，但它不是检查真或假值，而是检查值是否为 null 或空字符串。

isEmpty:No|Yes

它还可以接受 %s，如果您想输出值，如下所示，如果值为空则显示 'Nothing'，如果存在则显示实际值

isEmpty:Nothing|%s

加载修订历史

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

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

显示历史记录

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

为此，有几个辅助方法可以帮助显示更深入的信息，因此您可以显示类似 Chris changed plan from bronze to gold 的内容。

上面的结果将是这样的

@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(array('title', 'content')); // Disables title and content

贡献

鼓励并欢迎贡献；为了保持组织有序，所有错误和请求都应在GitHub issues标签中打开，地址为 venturecraft/revisionable/issues

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

遇到问题了吗？

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

• StackOverflow revisionable 标签
• GitHub Issues

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