README

您是否希望在项目中为任何模型都保存版本历史，而无需为此做任何工作。只需将 RevisionableTrait 特性添加到您的模型中，您就可以立即拥有它，并能够显示类似以下的历史记录

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

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

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

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

Revisionable 支持由 Sentry by Cartalyst 提供的 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 格式化器（请参见格式化输出以了解示例。）

存储强制删除

默认情况下，模型的强制删除不会作为修订记录存储。

如果您想将强制删除存储为修订记录，可以通过在模型中设置 revisionForceDeleteEnabled 为 true 来覆盖此行为，如下所示：

protected $revisionForceDeleteEnabled = true;

在这种情况下，created_at 字段将作为键存储，其 oldValue() 值等于模型创建日期，而 newValue() 值等于 null。

注意！ 请小心开启此设置！因为现在保存在修订记录中的模型已经不存在，所以您将无法获取其对象或其关系。

存储创建

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

如果您想将创建作为修订记录存储，可以通过在模型中设置 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

为空

这依赖于布尔值，但不是测试true或false值，而是检查值是否为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()

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

加载的用户模型取决于您在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'标签。

venturecraft / revisionable

维护者

详细信息