README

轻松为任何Eloquent模型创建修订历史

namespace App;

use Convenia\Revisionable\RevisionableTrait;

class Article extends Eloquent {
  
    use RevisionableTrait;
}

一切就绪！

该项目是基于 https://github.com/VentureCraft/revisionable 的分支，并进行了一些改进和新功能

如果需要使用旧的1.x版本，可以使用 v1 README

安装

通过 composer (推荐)

composer require convenia/revisionable:^2.0

接下来，您必须安装服务提供者

// config/app.php
'providers' => [
    ...
    Convenia\Revisionable\RevisionableServiceProvider::class,
];

您可以使用以下命令发布迁移：

php artisan vendor:publish --provider="Convenia\Revisionable\RevisionableServiceProvider" --tag="migrations"

迁移发布后，您可以通过运行迁移来创建修订表：

php artisan migrate

文档

• 实现
  • 软删除
  • 创建
• 贡献

实现

namespace App;

use Convenia\Revisionable\RevisionableTrait;

class Article extends Eloquent {
  
    use RevisionableTrait;
}

如果需要，您可以在模型中将 $revisionEnabled 设置为 false 来禁用修订。这如果您想暂时禁用修订，或者想创建一个继承自 revisionable 的基模型，但希望某些模型禁用 revisionable，这将很有用。

namespace App;

use Convenia\Revisionable\RevisionableTrait;

class Article extends Eloquent {
  
    use RevisionableTrait;
    
    protected $revisionEnabled = false;
}

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

namespace App;

use Convenia\Revisionable\RevisionableTrait;

class Article extends Eloquent {
  
    use RevisionableTrait;
        
    protected $historyLimit = 500; //Stop tracking revisions after 500 changes have been made.
}

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

namespace App;

use Convenia\Revisionable\RevisionableTrait;

class Article extends Eloquent {
  
    use RevisionableTrait;
            
    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.
}

您可以通过调用 withoutRevision() 和 withRevision() 方法来暂停或临时设置修订。

    Article::withoutRevision();
    $article = Article::create(['title' => 'Amazing Article']);
    $article->title = 'New amazing Article';
    $article->save();
    ...
    Article::withRevision();
    $article->body = 'Text body of an amazing article';
    $article->save();

然而，这不会覆盖 revisionEnabled 变量。如果您在已将 $revisionEnabled 设置为 false 的模型上调用 withRevision() 方法，则修订将不会发生。

不同的列名和模型名

有时，一个模型可以有一个关系，其中关联的列不遵循 eloquent 模式，需要指定外键。在这些情况下，您需要声明一个名为 divergentRelations 的数组，其中列名指向模型名（小写）。这使得在使用 revision 的 newValue 或 oldValue 方法时，可以查询关系字段值（如名称或标题）。

class Article extends Model
{
    public $divergentRelations = [ 
        'quoted_id' => 'quotedauthors',
    ]; 
    public function quotedAuthors() 
    {
        return $this->belongsTo(QuotedAuthors::class, 'quoted_id');
    }
}

class QuotedAuthor extends Model
{
    public function articles()
    {
        return $this->hasMany(Article::class);
    }
}
    
    ...
    $newQuotedAuthor = QuotedAuthor::create(['name' => 'New Quoted Author']);
    $article->quoted_id = $newQuotedAuthor->id;
    $article->save();
    $revision = $article->revisionHistory()->first();
    $revision->newValue() = 'New Quoted Author';

如果您未设置 $divergentRelations 数组并尝试获取修订的 newValue，则将获取 ID 而不是名称或标题；

class Article extends Model
{
    public function quotedAuthors() 
    {
        return $this->belongsTo(QuotedAuthors::class, 'quoted_id');
    }
}

class QuotedAuthor extends Model
{
    public function articles()
    {
        return $this->hasMany(Article::class);
    }
}
    
    ...
    $newQuotedAuthor = QuotedAuthor::create(['name' => 'New Quoted Author']);
    $article->quoted_id = $newQuotedAuthor->id;
    $article->save();
    $revision = $article->revisionHistory()->first();
    $revision->newValue() = 1 ;

存储软删除

默认情况下，如果您的模型支持软删除，revisionable 将存储此操作以及任何恢复作为模型的更新。

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

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

存储创建

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

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

protected $revisionCreationsEnabled = true;

格式输出

您可以使用（并且鼓励使用）模型中的 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

贡献

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