README

Approval是一个Laravel包，它提供了一种简单的方式来在数据持久化之前批准新的模型数据。

安装

您可以通过Composer安装此包

composer require cjmellor/approval

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="approval-migrations"
php artisan migrate

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="approval-config"

这是已发布配置文件的内容

return [
    'approval' => [
        /**
         * The approval polymorphic pivot name
         *
         * Default: 'approvalable'
         */
        'approval_pivot' => 'approvalable',
    ],
];

此配置允许您更改多态关系名。尽管如此，它应以able结尾。

用法

注意

此包使用枚举，因此必须使用PHP >= 8.1和Laravel 10。

注意 此包不会为您批准/拒绝数据，它只是将新的/修改后的数据存储到数据库中。如何实现批准或拒绝模型的功能由您决定。

将MustBeApproved特质添加到您的模型中，现在数据将被存储在approvals表中，以便您批准或拒绝。

例如，您将其添加到Post模型中，每次创建或更新帖子时，所有脏数据都将作为JSON存储在数据库中，供您处理。

<?php

use Cjmellor\Approval\Concerns\MustBeApproved;

class Post extends Model
{
    use MustBeApproved;

    // ...
}

使用此特质的所有模型现在将存储在一个新表中 -- approvals。这是一个多态关系。

以下是关于approvals表中列的一些信息

approvalable_type => 要批准的模型类的名称

approvalable_id => 要批准的模型ID

state => 批准状态。这使用枚举类。此列被转换为ApprovalStatus枚举类

new_data => 模型中创建或更新的所有字段。这是一个JSON列。此列被转换为AsArrayObject 转换

original_data => 在更新之前模型中的所有字段。这是一个JSON列。此列被转换为AsArrayObject 转换

rolled_back_at => 此操作上次回滚到原始状态的时间戳

audited_at => 设置状态的用户的ID

foreign_key => 要批准的模型的键

绕过批准检查

如果您想检查模型数据是否将被绕过，请使用isApprovalBypassed方法。

return $model->isApprovalBypassed();

新模型的键

注意

建议您阅读以下部分，了解此包中外键的工作方式。

重要

默认情况下，外键始终为user_id，因为这是Laravel中最常用的外键。

如果您通过模型直接创建新模型，例如。

Post::create(['title' => 'Some Title']);

请确保也添加外键到模型中，例如。

Post::create(['title' => 'Some Title', 'user_id' => 1]);

现在，当模型发送进行批准时，外键将被存储在foreign_key列中。

自定义外键

如果您的模型不使用user_id作为外键，则可以通过向模型中添加此方法来自定义它

public function getApprovalForeignKeyName(): string
{
    return 'author_id';
}

作用域

该包为Builder提供了一些辅助方法，利用自定义作用域 - ApprovalStateScope

默认情况下，所有对approvals表的查询都将返回所有状态的模型。

有三个方法可以帮助您检索审批的状态。

<?php

use App\Models\Approval;

Approval::approved()->get();
Approval::rejected()->get();
Approval::pending()->count();

您还可以为审批设置一个状态。

<?php

use App\Models\Approval;

Approval::where('id', 1)->approve();
Approval::where('id', 2)->reject();
Approval::where('id', 3)->postpone();

如果您需要重置状态，可以使用withAnyState辅助方法。

辅助方法

条件辅助方法被使用，因此您可以在满足条件时设置审批的状态。

$approval->approveIf(true);
$approval->rejectIf(false);
$approval->postponeIf(true);

$approval->approveUnless(false);
$approval->rejectUnless(true);
$approval->postponeUnless(false);

事件

一旦模型的状态被更改，就会触发一个事件。

ModelApproved::class
ModelPostponed::class
ModelRejected::class

持久化数据

默认情况下，一旦您批准了一个模型，它将被插入到数据库中。

如果您不想在批准时将数据持久化到数据库，请在approve方法上设置一个false标志。

Approval::find(1)->approve(persist: false);

回滚

如果您需要回滚审批，可以使用rollback方法。

注意

默认情况下，回滚将绕过重新添加到approvals表。

Approval::first()->rollback();

这将还原数据并将状态设置为pending，并接触rolled_back_at时间戳，以便您记录回滚的时间。

如果您希望回滚可以被重新批准，请将bypass参数作为false传递给rollback方法。

Approval::first()->rollback(bypass: false); // default is true

条件回滚

回滚可以是条件性的，因此您可以在满足条件时回滚审批。

Approval::first()->rollback(fn () => true);

事件

当模型被回滚时，将触发一个带有回滚的审批模型和回滚用户的ModelRolledBack事件。

// ModelRolledBackEvent::class

public Model $approval,
public Authenticatable|null $user,

禁用审批

如果您不希望模型数据被批准，可以使用withoutApproval方法绕过。

$model->withoutApproval()->update(['title' => 'Some Title']);

指定可批准的属性

默认情况下，模型的所有属性将通过审批流程，但如果您只想让某些属性通过此流程，您可以使用模型中的approvalAttributes属性来指定它们。

<?php

use Cjmellor\Approval\Concerns\MustBeApproved;

class Post extends Model
{
    use MustBeApproved;

    protected array $approvalAttributes = ['name'];

    // ...
}

在这个例子中，只有该模型的名称属性将通过审批流程，对其他属性的任何更改都将绕过审批流程。

如果您从模型中省略了approvalAttributes属性，则所有属性都将通过审批流程。

测试

composer test

更改日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请尽可能详细地打开一个关于您想要实现什么内容的PR。

鸣谢

• Chris Mellor

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。