README

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

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

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

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

与第三方Auth / Eloquent扩展一起使用

Revisionable 支持

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

安装

Revisionable 可以通过 composer 安装，详细信息请见 packagist，在此处。

运行composer require 下载包

php composer.phar require 'venturecraft/revisionable' '~1.0'

接下来，将 RevisionableServiceProvider 添加到您的应用程序配置中的提供商列表中

    Venturecraft\Revisionable\RevisionableServiceProvider::class,

最后，发布迁移并运行它

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

实现

新的，基于特质实现

对于您想要保留修订历史记录的任何模型，请包含 revisionable 命名空间并在您的模型中使用 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;
}

您还可以在进行了X次修订后通过将$historyLimit设置为想要保留的修订次数来停止修订。

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;

输出格式

您可以使用eloquent accessors在模型中设置值的输出，有关更多信息，请参阅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

是否为空

这基于布尔值，但不是测试true或false值，而是检查值是否为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(array('title', 'content')); // Disables title and content

贡献

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

所有pull请求都应该提交到develop分支，这样在合并到master分支之前可以进行测试。

遇到问题了吗？

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

如果您更愿意在公共场合发布您的问题到StackOverflow，请使用'revisionable'标签。

jaapmoolenaar.nl / revisionable

维护者

详细信息