aurorawebsoftware/arflow

ArFlow 是一个 Laravel 扩展包，允许您为 Laravel Eloquent 模型实现工作流管理。

维护者

详细信息

github.com/AuroraWebSoftware/ArFlow

主页

源代码

问题

安装: 1,027

依赖项: 1

建议者: 0

安全: 0

星标: 20

关注者: 1

分支: 1

开放问题: 3

1.1.1 2024-02-28 10:21 UTC

Requires

Requires (Dev)

MIT a9ca6b3f97968b5e0e5256c1044fe59deca30be9

  • AuroraWebSoftwareTeam <websoftwareteam.woop@aurorabilisim.com>

laravelAuroraWebSoftwarearflow

This package is auto-updated.

Last update: 2024-09-28 11:30:13 UTC

README

img.png

介绍

ArFlow 是一个 Laravel 扩展包，允许您为 Laravel Eloquent 模型实现工作流管理。本文档提供了如何有效使用 ArFlow 的全面指南。

关键概念

1. 工作流

工作流代表模型可以经历的一系列状态和转换。关于工作流的关键点

  • 每个模型可以关联一个或多个工作流。
  • 工作流定义了模型的可能状态和转换。

2. 状态

状态代表模型在工作流中可以存在的不同阶段。关于状态的关键点

  • 每个工作流有一组预定义的状态。
  • 模型在任何给定时间可以处于这些状态中的任何一个。

3. 转换

转换定义了模型在工作流中从一个状态移动到另一个状态的规则和条件。关于转换的关键点

  • 转换指定了模型可以移动到的状态。
  • 它们可以与 守卫、动作 和 成功作业 相关联。

4. 守卫

守卫是转换必须满足的条件或检查。关于守卫的关键点

  • 如果条件不满足，守卫将阻止转换。
  • 它们被定义为类，可以自定义以适应您应用程序的逻辑。

5. 动作

动作是在转换期间执行的任务或操作。关于动作的关键点

  • 动作在转换发生时执行。
  • 它们被定义为类，可以自定义以执行特定任务。

6. 成功作业

成功作业是在成功转换后分发的作业或任务。关于成功作业的关键点

  • 它们允许您在转换后执行后台任务。
  • 用于记录、通知或其他转换后操作。

7. 初始状态

每个工作流都有一个初始状态，模型在工作流应用时进入该状态。关于初始状态的关键点

  • 它是工作流中模型的开端。
  • 当工作流首次应用时，模型处于初始状态。

安装

您可以通过 Composer 安装 ArFlow 扩展包。运行以下命令

composer require aurorawebsoftware/arflow

接下来，您需要发布扩展包配置和迁移文件

php artisan vendor:publish --tag=arflow-config

别忘了运行迁移

php artisan migrate

模型设置

要在您的模型中使用 ArFlow，请按照以下步骤操作

  1. 在您的模型类中使用 HasState 特性。

此特性提供允许模型成为工作流一部分、获取配置、获取初始状态和执行转换的功能。

use AuroraWebSoftware\ArFlow\Traits\HasState;

class YourModel extends Model
{
    use HasState;

    // Your model properties and methods
}
  1. 在您的模型类中实现 StateableModelContract 接口。

此接口确保您的模型具有作为可状态实体所需的方法。这包括设置工作流属性、状态属性和元数据属性。您还可以确定支持的工作流、应用工作流和执行转换。以下是一些示例用法

use AuroraWebSoftware\ArFlow\Contacts\StateableModelContract;

class YourModel extends Model implements StateableModelContract
{
    use HasState;

    public static function supportedWorkflows(): array
    {
        return ['workflow1', 'workflow3'];
    }

    // Your model properties and methods
}
  1. (可选) 如果您想更改默认值或跳过此步骤，请在模型类中定义与工作流相关的模型属性
class YourModel extends Model implements StateableModelContract
{
    use HasState;

    public static function workflowAttribute(): string
    {
        return 'workflow';
    }

    public static function stateAttribute(): string
    {
        return 'state';
    }

    public static function stateMetadataAttribute(): string
    {
        return 'state_metadata';
    }

    // Your model properties and methods
}

用法

现在您已经设置了模型，您可以应用工作流并执行转换

应用工作流

要应用工作流到模型实例，请使用 applyWorkflow 方法

$model = YourModel::find($id);
$model->applyWorkflow('workflow_name');

获取模型的当前工作流

$currentWorkflow = $instance->currentWorkflow();

获取模型当前状态

$currentState = $instance->currentState();

检查过渡状态

您可以使用canTransitionTo方法来检查是否允许过渡到特定状态

$model = YourModel::find($id);
if ($model->canTransitionTo('new_state')) {
    // Transition is allowed
} else {
    // Transition is not allowed
}

过渡到状态

要将模型过渡到新状态，请使用transitionTo方法

$model = YourModel::find($id);
$model->transitionTo('new_state');

获取定义的和允许的过渡状态

您可以检索模型定义的和允许的过渡状态

// Defined transition states
$definedStates = $model->definedTransitionStates();

// Allowed transition states
$allowedStates = $model->allowedTransitionStates();

过渡守卫结果

您还可以使用transitionGuardResults方法获取过渡守卫结果

$results = $model->transitionGuardResults('new_state');

此方法返回一个过渡守卫结果的集合，可用于检查守卫是否允许过渡。

配置

您可以在config/arflow.php文件中配置您的流程。在那里定义您的流程、状态、过渡、守卫和操作。

示例配置

以下是一个工作流程的示例配置

蓝图宏

为了简化将状态列添加到迁移中，提供了一个蓝图宏：此宏$table->arflow()将创建三个列：工作流程、状态和状态元数据。

// your_migration.php
Schema::create('your_model', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->arflow();
    $table->timestamps();
});
// config/arflow.php
return [
    'workflows' => [
        'workflow_name' => [
            'states' => ['state1', 'state2', 'state3'],
            'initial_state' => 'state1',
            'transitions' => [
                'transition_name' => [
                    'from' => ['state1'],
                    'to' => 'state2',
                    'guards' => [
                        [GuardClass::class, ['permission' => 'approval']],
                    ],
                    'actions' => [
                        [ActionClass::class, ['param1' => 'value1']],
                    ],
                    'success_metadata' => ['key' => 'value'],
                    'success_jobs' => [JobClass::class],
                ],
                // Define more transitions as needed
            ],
        ],
        // Define additional workflows
    ]
];

创建过渡守卫

示例过渡守卫实现。

namespace App\ArFlow\Guards;

use AuroraWebSoftware\ArFlow\Contacts\StateableModelContract;
use AuroraWebSoftware\ArFlow\Contacts\TransitionGuardContract;
use AuroraWebSoftware\ArFlow\DTOs\TransitionGuardResultDTO;

class PermissionTransitionGuard implements TransitionGuardContract
{
    private StateableModelContract $model;
    private string $from;
    private string $to;
    private array $parameters;

    public function __construct() {}
    
    public function boot(StateableModelContract &Model $model, string $from, string $to, array $parameters): void
    {
        $this->model = $model;
        $this->from = $from;
        $this->to = $to;
        $this->parameters = $parameters;
        
        // You can perform any initialization here.
    }

    public function handle(): TransitionGuardResultDTO
    {
        // Implement your logic to check permissions here.
        // For example, check if the user has the required role to make the transition.

        // If the permission check passes, allow the transition:
        return TransitionGuardResultDTO::build(TransitionGuardResultDTO::ALLOWED);

        // If the permission check fails, deny the transition:
        // return TransitionGuardResultDTO::build(TransitionGuardResultDTO::DENIED, 'Permission denied.');
    }
}

创建过渡操作

示例过渡操作。

use AuroraWebSoftware\ArFlow\Contacts\TransitionActionContract;

class SendNotificationAction implements TransitionActionContract
{
    public function boot(StateableModelContract&Model $model, string $from, string $to, array $parameters = []): void {}

    public function handle(): void
    {
        // Send a notification when the transition is successful.
    }

    public function failed(): void
    {
        // Handle any cleanup or error logging here if the action fails.
    }
}

创建过渡成功作业

示例过渡作业。

namespace AuroraWebSoftware\ArFlow\Tests\Jobs;

use AuroraWebSoftware\ArFlow\Abstracts\AbstractTransitionSuccessJob;
use AuroraWebSoftware\ArFlow\Contacts\StateableModelContract;
use Illuminate\Database\Eloquent\Model;

class TestTransitionSuccessJob extends AbstractTransitionSuccessJob
{
    /**
     * Execute the job.
     * @param StateableModelContract&Model $model
     * @param string $from
     * @param string $to
     * @param array $parameters
     */
    public function handle(StateableModelContract & Model $model, string $from, string $to, array $parameters = []): void
    {
        // Process 
    }
}

贡献

  • php 8.2+
docker-compose up -d
composer format
composer analyse
composer test
composer test-coverage

此文档应帮助您开始在Laravel应用程序中使用ArFlow包。请根据您项目的需求自由探索更多功能和配置。

有关更多信息，请参阅包的GitHub存储库或联系我们的支持人员。