README

简介

此包使您的Laravel应用程序中的Eloquent模型实现多级审批工作流程。如果您有需要经过多个审批者审查和批准后才能执行的模式，此包提供灵活的审批过程以满足该需求。

Laravel 10.0或更高版本

此包依赖于现有的Role管理。这可以是自定义角色管理或Spatie的laravel permissions等包。

安装

1. 使用composer安装

composer require ringlesoft/laravel-process-approval

2. 发布文件（可选）

此包提供可发布的文件，包括配置、迁移和视图。您可以使用以下命令发布这些文件：

php artisan vendor:publish --provider="RingleSoft\LaravelProcessApproval\LaravelProcessApprovalServiceProvider"

您可以通过在发布命令中提供--tag选项来发布特定文件。可用选项包括approvals-migrations、approvals-config、approvals-views、approvals-translations。
例如

php artisan vendor:publish --provider="RingleSoft\LaravelProcessApproval\LaravelProcessApprovalServiceProvider" --tag="approvals-migrations"

3. 运行迁移

此包包含四个迁移文件。在开始使用此包之前，请运行artisan migrate命令。

php artisan migrate

4. 创建审批流程和步骤

此包依赖于您默认数据库中的审批流程和步骤。这是为了在系统中实现多个审批流程。您可以实施自己的创建和管理流程的方式。然而，有一些可用的命令行功能可以帮助您轻松开始。

i. 创建新的流程

在您的终端上运行以下命令以创建新流程。

 php artisan process-approval:flow add FundRequest

ii. 为流程创建步骤

php artisan process-approval:step add

这将显示可用的流程列表。选择您要添加步骤的流程，然后选择角色和审批动作。

iii. 删除流程

php artisan process-approval:flow remove

这将显示可用的流程列表。选择您要删除的步骤并按回车键。

iv. 删除步骤

php artisan process-approval:step remove

这将显示可用的步骤列表。选择您要删除的步骤并按回车键。

v. 列出所有流程

php artisan process-approval:flow list

这将显示所有可用的流程和步骤列表

用法

1. 将`AprovableModel`实现到您的审批模型中

class FundRequest extends Model implements ApprovableModel
{

   // Your model content

}

2. 将`Approvable`特性应用到模型中

class FundRequest extends Model implements ApprovableModel
{
    use \RingleSoft\ProcessApproval\Traits\Approvable;
   // Your model content

}

3. 实现方法`onApprovalCompleted()`。

此包依赖于您的模型中的一个回调方法，用于提交最后一步审批并标记审批流程为完成。您应该实现此方法并返回true以最终完成审批或返回false以撤销最后一步审批。这在执行特定任务时非常有用，当审批流程完成时。

class FundRequest extends Model implements ApprovableModel
{
use \RingleSoft\ProcessApproval\Traits\Approvable;
   // Your model content
   
    public function onApprovalCompleted(ProcessApproval $approval): bool
    {
        // Write logic to be executed when the approval process is completed
        return true;
    }
}

4. 在您的模型显示页面上放置`<x-ringlesoft-approval-actions>`组件，并使用`model`参数提供模型实例。

    <x-ringlesoft-approval-actions :model="$fundRequest" />

当前，UI使用tailwind或bootstrap实现。将很快提供对纯CSS和JS的支持。您可以通过修改配置文件中的css_library设置在两者之间切换。此外，您还有发布视图并按需自定义它们的选项。

配置

您可以通过以下命令发布此包的配置文件process_approval.php并修改变量以符合您特定的需求。如果您想发布文件，请使用以下命令：

php artisan vendor:publish --provider="RingleSoft\LaravelProcessApproval\LaravelProcessApprovalServiceProvider" --tag="approvals-config"

可配置参数

roles_model - 指定与角色表相关的模型的完整类名。（默认为Spatie的laravel-permissions（Spatie\Permissions\Models\Role））
users_model - 指定代表已认证用户的模型。（默认为 App\Models\User）。
models_path - 指定应用程序中模型的默认命名空间。（默认为 App\Models）。
approval_controller_middlewares - 指定您希望应用到 ApprovalController 的中间件。（通常应为 ['auth']）。
css_library - 指定用于样式化 UI 组件的 CSS 库（bootstrap/tailwind）。（默认为 Tailwind CSS）。
multi_tenancy_field - 指定用户表中的多租户字段。（默认为 tenant_id）

模型提交

默认情况下，当模型被标记为“已提交”时，模型就准备好进行审批。这提供了在审批流程开始之前对模型进行编辑和其他操作的机会。如果您希望在新创建的模型提交之前将其隐藏起来，以便审批者无法看到，此功能特别有用。

如果希望模型在创建时自动提交，可以将以下属性添加到模型中

public bool $autoSubmit = true;

否则，该软件包将在模型的显示页面上显示提交按钮，以便创建者可以提交模型。

暂停审批流程

有时您可能希望在继续审批之前添加自己的操作来中断审批流程。您可以通过向可审批模型添加 pauseApprovals(): mixed 方法来暂停审批。

public function pauseApprovals() {
    return true;
}

如果此方法返回 true，则审批操作 UI 将消失，您将能够实现其他逻辑。如果方法返回 'ONLY_ACTIONS'，则将显示现有的审批，但审批操作将被隐藏并禁用。

审批签名

如果您想为用户使用签名，请将 getSignature() 方法添加到您的 User 模型中，并使其返回用户的签名图像 URL。

Class User extends Model {
    ...
    
    public function getSignature(){
        return $this->signature_path; // Return the path to user's signature
    }
}

如果未指定，则软件包将显示审批的 check 图标和拒绝的 times 图标。

审批摘要

如果您想在列出模型时显示审批流程的摘要，可以使用 <x-ringlesoft-approval-status-summary> 组件。此组件返回包含代表每个审批步骤的图标的 HTML 代码：check 图标代表 批准，times 图标代表 拒绝 或 废弃，以及 exclamation 图标代表 挂起。

    $fundRequest->getApprovalSummaryUI();

事件

在审批工作流程的不同阶段，该软件包会分发事件，以便挂钩到流程中。

ProcessSubmittedEvent - 当新的可审批模型被提交时分发。
ProcessApprovedEvent - 当可审批模型被审批者批准时分发。
ProcessRejectedEvent - 当可审批模型被审批者拒绝时分发。
ProcessReturnedEvent - 当可审批模型被审批者退回到上一步时分发。
ProcessDiscardedEvent - 当可审批模型被审批者丢弃时分发。
ProcessApprovalCompletedEvent - 当完整的审批工作流程完成时分发，无论是批准还是废弃。
ApprovalNotificationEvent - 在审批操作期间分发，带有有关发生什么的通知消息。

显示通知

要显示审批通知，请订阅 ApprovalNotificationEvent 事件。

1. 创建监听器

使用 artisan 命令生成事件的监听器

php artisan make:listener ApprovalNotificationListener --event=\\RingleSoft\\LaravelProcessApproval\\Events\\ApprovalNotificationEvent

2. 实现监听器逻辑

在生成的 ApprovalNotificationListener 类中，在 handle() 方法内实现逻辑。此方法将在 ApprovalNotificationEvent 事件被触发时执行。根据应用程序的要求自定义通知内容和交付方式。

示例监听器实现

class ApprovalNotificationListener
{
    ...
    /**
     * Handle the event.
     */
    public function handle(ApprovalNotificationEvent $event): void
    {
        session()->flash('success', $event->message);
    }
}

3. 注册监听器

在您的 EventServiceProvider 类中注册监听器，以将 ApprovalNotificationEvent 事件与您的 ApprovalNotificationListener 相关联

protected $listen = [
    ApprovalNotificationEvent::class => [
        ApprovalNotificationListener::class,
    ],
];

使用您自己的方法从 session() 显示通知

通知审批者

当文档等待审批时，您可以订阅 ProcessSubmittedEvent 和 ProcessApprovedEvent 事件并向他们发送通知。

以下是在 ProcessSubmittedListener 监听器中向下一级审批者发送通知的示例

    public function handle(ProcessSubmittedEvent $event): void
    {
        $nextApprovers = $event->approvable->getNextApprovers();
        foreach ($nextApprovers as $nextApprover) {
            $nextApprover->notify(new AwaitingApprovalNotification($event->approvable));
        }
    }

辅助方法

此包向可审批模型添加了多个辅助方法。包括

过滤器

approved() [静态]: 返回一个过滤器，仅筛选出已批准的模型条目（返回 Illuminate\Database\Eloquent\Builder）示例
```
    FundRequest::approved()->get();
```
rejected() [静态]: 返回一个过滤器，仅筛选出已拒绝的模型条目（返回 Illuminate\Database\Eloquent\Builder）示例
```
    FundRequest::rejected()->get();
```
discarded() [静态]: 返回一个过滤器，仅筛选出已丢弃的模型条目（返回 Illuminate\Database\Eloquent\Builder）示例
```
    FundRequest::discarded()->get();
```
returned() [静态]: 返回一个过滤器，仅筛选出已退回的模型条目（返回 Illuminate\Database\Eloquent\Builder）示例
```
    FundRequest::returned()->get();
```
submitted() [静态]: 返回一个过滤器，仅筛选出已提交的模型条目（返回 Illuminate\Database\Eloquent\Builder）示例
```
    FundRequest::submitted()->get();
```

操作

submit([user: Authenticatable|null = null]): bool|RedirectResponse|ProcessApproval: 提交模型
approve([comment = null], [user: Authenticatable|null = null]): bool|RedirectResponse|ProcessApproval: 批准模型
reject([comment = null], [user: Authenticatable|null = null]): bool|ProcessApproval: 拒绝模型
return([comment = null], [user: Authenticatable|null = null]): bool|ProcessApproval: 将模型退回上一步
discard([comment = null], [user: Authenticatable|null = null]): bool|ProcessApproval: 丢弃模型
return([comment = null], [user: Authenticatable|null = null]): bool|ProcessApproval: 将模型退回上一步

杂项

isApprovalCompleted(): bool: 检查模型的审批流程是否已完成
isSubmitted(): bool: 检查模型是否已提交
isRejected(): bool: 检查模型是否被拒绝
isDiscarded(): bool: 检查模型是否被丢弃
isReturned(): bool: 检查模型是否被退回上一步
nextApprovalStep(): null|ProcessApprovalFlowStep: 返回模型的下一审批步骤
previousApprovalStep(): null|ProcessApprovalFlowStep: 返回模型的上一审批步骤
canBeApprovedBy(user: Authenticatable|null): bool|null: 检查模型当前是否可以被指定用户批准。
onApprovalCompleted(approval: ProcessApproval): bool: 当审批流程完成后调用的回调方法。此方法必须实现，并且必须返回 true 以使最后一步批准成功。否则，最后一步批准将被回滚。
getNextApprovers(): Collection: 返回当前步骤中可以审批该模型的用户列表。

关系

approvals(): morphMany - 返回模型的全部审批
lastApproval(): morphOne - 返回模型的最后一步审批 (Models\ProcessApproval)
approvalStatus(): morphOne - 返回模型的状态对象 (Models\ProcessApprovalStatus)

播种

如果您想将审批流程播种到数据库中，此包提供了一个静态方法 makeApprovable(): bool 来为模型创建一个新的审批流程。此方法可用于将必要的审批流程和步骤播种到数据库中。

此方法接受两个参数

$steps: 一个数组，定义了用作审批步骤的角色。
$name: （可选）审批流程的名称。

基本用法

当第一个参数是一个整数扁平数组时，该方法会创建一个新的审批流程，以数组项作为 role_id，并为每个步骤设置 ApprovalTypeEnum::APPROVE 作为默认操作。

    FundRequest::makeApprovable([1,2,3]);

高级用法

当第一个参数是一个关联数组 [int => ApprovalTypeEnum, ...] 时，该方法会创建一个新的审批流程，以数组键（int）作为 role_id，以值（ApprovalTypeEnum）作为相应的操作。

    FundRequest::makeApprovable([
        1 => ApprovalTypeEnum::APPROVE,
        3 => ApprovalTypeEnum::CHECK
    ]);

复杂用法

当第一个参数是一个数组数组时，该方法会创建一个新的审批流程，步骤可以接受来自子数组的 [role_id => int, action => ApprovalTypeEnum]。

    FundRequest::makeApprovable([
                [
                    'role_id' => 2,
                    'action' => ApprovalTypeEnum::CHECK->value
                ],
                [
                    'role_id' => 1,
                    'action' => ApprovalTypeEnum::CHECK->value
                ],
                [
                    'role_id' => 1,
                    'action' => ApprovalTypeEnum::APPROVE->value
                ]
            ]
        );

此选项允许您为同一角色创建具有多个步骤的流程，每个步骤具有不同的操作或发生。

多租户

此软件包通过在用户表中配置一个列来支持多租户。您可以使用 multi_tenancy_field 配置选项指定列名。当登录用户设置了 tenant_id 字段时，软件包将使用该值来过滤审批步骤。这样，您可以为不同的租户具有不同的步骤的审批流程。

测试

要测试此软件包，切换到 tests 分支，并运行 composer install 来安装依赖项，然后运行 vendor/bin/testbench package:test 来执行测试。

贡献

我会告诉你何时可以做出贡献 😜。

许可证

Laravel Process Approval 是在 MIT 许可证下发布的开源软件。

支持

联系方式

在 X 上关注我：@ringunger
给我发邮件：ringunger@gmail.com
网站： https://ringlesoft.com

ringlesoft / laravel-process-approval

维护者

详细信息