wppd/laravel-state-machine

Winzou State Machine 服务提供程序用于 Laravel

此软件包的规范仓库似乎已删除，因此已冻结该软件包。

维护者

详细信息

github.com/wppd/laravel-state-machine

主页

源代码

安装次数: 3,946

依赖关系: 0

建议者: 0

安全: 0

星标: 1

关注者: 0

分支: 43

3.0.1 2020-03-20 09:28 UTC

Requires

Requires (Dev)

MIT 8eeac95c5a9edee27bf6495e1d0d9877d82efe27

eventstatelaravelstatemachine

This package is auto-updated.

Last update: 2021-02-20 11:38:37 UTC

README

Latest Version on Packagist Software License Build Status Scrutinizer Code Quality StyleCI

这是一个用于 winzou/state-machine 的 Laravel 服务提供程序。它提供了对 StateMachineFactory 的依赖注入。您还可以使用 Laravel 的服务容器来解析回调的类方法。还提供了一个门面以方便使用。

安装

您可以通过 composer 安装此软件包。此软件包需要 Laravel 7.0 或更高版本。

在您的 composer.json 中，添加以下部分

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/sebdesign/state-machine"
    }
]

然后使用命令行界面安装软件包

composer require sebdesign/laravel-state-machine

版本

如果您需要在较旧的 Laravel 安装中安装此软件包，请使用下表查找兼容版本。

软件包 Laravel PHP
^3.0 ^7.0 ^7.2.5
^2.0 5.5.* - ^6.0 ^7.0
^1.0 5.1.* - 5.8.* ^5.5.9 | ^7.0

自 5.5 版本以来，Laravel 使用软件包自动发现，因此您无需手动添加 ServiceProvider 和门面。如果您不使用自动发现或您正在使用较旧的版本，请将服务提供程序和门面添加到 config/app.php 中。

<?php

'providers' => [
    Sebdesign\SM\ServiceProvider::class,
],

'aliases' => [
    'StateMachine' => Sebdesign\SM\Facade::class,
],

配置

发布 config/state-machine.php 中的配置文件。

php artisan vendor:publish --provider="Sebdesign\SM\ServiceProvider"

请参阅 StateMachineBundle 的文档以获取所有可用选项。

使用方法

<?php

// Get the article
$article = App\Article::find($id);

// Get the state machine for this article, and graph called "simple"

// Using the facade
$stateMachine = StateMachine::get($article, 'simple');

// Or using the service container with dependency injection
public function method(SM\Factory\FactoryInterface $factory)
{
    $stateMachine = $factory->get($article, 'simple');
}

现在您可以使用 $stateMachine 来交互 $article 的状态。

<?php

// Get the actual state of the object
$stateMachine->getState();

// Get all available transitions
$stateMachine->getPossibleTransitions();

// Check if a transition can be applied: returns true or false
$stateMachine->can('approve');

// Apply a transition: returns true or throws an SM\SMException
$stateMachine->apply('publish');

// Apply a transition without throwing an exception: returns true or false
$stateMachine->apply('publish', true);

回调

回调用于保护转换或在应用转换前后执行一些代码。此软件包增加了使用 Laravel 的服务容器来解析回调的能力。

例如：

您想调用 MyService 类的 handle 方法来确定状态机是否可以应用 submit_changes 转换。

<?php

'callbacks' => [
    // will be called when testing a transition
    'guard' => [
        'guard_on_submitting' => [
            // call the callback on a specific transition
            'on' => 'submit_changes',

            // will call the method of this class
            'do' => ['MyService', 'handle'],

            // arguments for the callback
            'args' => ['object'],
        ],
    ],
],

您可以使用数组格式指定回调，例如 ['Class', 'method']，或者使用 @ 分隔的字符串格式，例如 Class@method。

使用门面和策略

如果您不想使用自定义类/方法进行保护，您可以使用 Laravel 的授权门面或策略来确定是否可以应用转换。

您必须定义一个带有您想检查的能力名称的 can 键，而不是指定一个 do 键。自 Laravel 5.5 版本以来，您还可以指定一个能力数组，并将检查每个能力。

默认情况下，对象实例将作为参数传递给门面。您还可以通过在 args 键中指定它们来覆盖参数。

使用门面的示例

在这个例子中，我们定义了一个门面，它将接受 $article 作为参数。如果您不需要这个参数，您不需要在您的门面中定义这个参数。

<?php

use App\User;
use App\Article;

Gate::define('approve', function (User $user, Article $article) {
    //
});
<?php

'callbacks' => [
    'guard' => [
        'guard_on_approving' => [
            // call the gate on a specific transition
            'on' => 'approve',
            // will call Gate:allows('approve', $article)
            'can' => 'approve',
        ],
    ],
],

使用策略的示例

假设您为 Article 模型创建了一个名为 ArticlePolicy 的策略，它有一个 approve 方法。

您应该在 can 索引中定义 approve。这将相当于调用 $user->can('approve', $article)。

您还可以通过指定 args 数组来覆盖将传递给 approved 方法的参数。为了使策略类能够解析，您必须使用 object 作为第一个参数。例如：'args' => ['object', '"final_approval"'] 将相当于调用 $user->can('approve', [$article, 'final_approval'])。

<?php

namespace App\Policies;

use App\User;
use App\Article;

class ArticlePolicy
{
    public function approve(User $user, Article $article)
    {
        //
    }
}
<?php

'callbacks' => [
    'guard' => [
        'guard_on_approving' => [
            // call the policy on a specific transition
            'on' => 'approve',
            // will call Gate:allows('approve', $article)
            'can' => 'approve',
        ],
    ],
],

事件

在检查是否可以应用转换时，会触发 SM\Event\SMEvents::TEST_TRANSITION 事件。

在应用转换之前和之后，分别触发 SM\Event\SMEvents::PRE_TRANSITION 和 SM\Event\SMEvents::POST_TRANSITION 事件。

所有事件都接收一个 Sebdesign\SM\Event\TransitionEvent 实例。

如果您希望使用相同的监听器监听所有事件，可以使用 winzou.state_machine.* 通配符参数。

您可以在应用程序的 EventServiceProvider 中定义自己的监听器。例如：

<?php

use SM\Event\SMEvents;

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    SMEvents::TEST_TRANSITION => [
        \App\Listeners\CheckTransition::class,
    ],
    SMEvents::PRE_TRANSITION => [
        \App\Listeners\BeforeTransition::class,
    ],
    SMEvents::POST_TRANSITION => [
        \App\Listeners\AfterTransition::class,
    ],
    'winzou.state_machine.*' => [
        \App\Listeners\Transition::class,
    ],
];

上下文

在检查或应用转换时，您还可以通过数组传递额外的数据。此数组将传递给 Sebdesign\SM\Event\TransitionEvent。您可以在事件监听器或回调中使用 $event->getContext() 访问数组。

使用事件监听器的示例

<?php

// Reject the transition of the approval date is past
Event::listen(SMEvents::TEST_TRANSITION, function (TransitionEvent $event) {
    $context = $event->getContext();

    if ($context['approved_at']->isPast()) {
        $event->setRejected();
    }
});

// Check if a approve transition can be applied on some date
$stateMachine->can('approve', ['approved_at' => now()]);

使用回调的示例

<?php

// Setup an callback after publishing
[
    'callbacks' => [
        'after' => [
            'after_publishing' => [
                'on' => 'publish',
                'do' => [App\Actions\PublishArticleAction::class, 'execute'],
                'args' => ['object', 'event'],
            ],
        ],
    ],
];

// Save the publish date in your action
class PublishArticleAction
{
    public function execute(Article $article, TransitionEvent $event)
    {
        $context = $event->getContext();
        $article->update(['published_at' => $context['published_at']]);
    }
}

// Apply a publish transition on some date
$stateMachine->apply('publish', false, ['published_at' => now()]);

元数据

您可以选择在图、状态和转换中存储元数据。元数据存储在关联数组中，可以是您想要的任何内容。

<?php

return [
    'graphA' => [
        'class' => App\Article::class,

        'metadata' => [
            'title' => 'Article State Machine',
        ],

        'states' => [
            [
                'name' => 'pending_review',
                'metadata' => ['title' => 'Pending Review'],
            ],
        ],

        'transitions' => [
            'ask_for_changes' => [
                'from' => ['pending_review'],
                'to' => 'accepted',
                'metadata' => ['title' => 'Ask for changes'],
            ],
        ],
    ],
];

状态机对象提供了许多灵活的方法来获取元数据，无论是作为关联数组，还是通过键获取特定值。如果指定的键不存在，您还可以传递默认值或闭包。

从图中获取元数据

<?php

$stateMachine = StateMachine::get($article);

// ['title' => 'Article State Machine']
$stateMachine->metadata('graph');
$stateMachine->metadata()->graph();

// 'Article State Machine'
$stateMachine->metadata('title');

// 'Article State Machine'
$stateMachine->metadata('graph', 'title');
$stateMachine->metadata()->graph('title');

// null
$stateMachine->metadata('graph', 'invalid');
$stateMachine->metadata()->graph('invalid');

// 'default'
$stateMachine->metadata('graph', 'invalid', 'default');
$stateMachine->metadata()->graph('invalid', 'default');

从状态中获取元数据

$stateMachine = StateMachine::get($article);

// ['title' => 'Pending Review']
$stateMachine->metadata('state', 'pending_review');
$stateMachine->metadata()->state('pending_review');

// 'Pending Review'
$stateMachine->metadata('state', 'pending_review', 'title');
$stateMachine->metadata()->state('pending_review', 'title');

// null
$stateMachine->metadata('state', 'pending_review', 'invalid');
$stateMachine->metadata()->state('pending_review', 'invalid');

// 'default'
$stateMachine->metadata('state', 'pending_review', 'invalid', 'default');
$stateMachine->metadata()->state('pending_review', 'invalid', 'default');

从当前状态中获取元数据

<?php

$article->state = 'pending_review';
$stateMachine = StateMachine::get($article);

// ['title' => 'Pending Review']
$stateMachine->metadata('state');

// 'Pending Review'
$stateMachine->metadata('state', 'title');

// null
$stateMachine->metadata('state', 'invalid');

// 'default'
$stateMachine->metadata('state', 'invalid', 'default');

从转换中获取元数据

<?php

$stateMachine = StateMachine::get($article);

// ['title' => 'Ask for changes']
$stateMachine->metadata('transition', 'ask_for_changes');
$stateMachine->metadata()->transition('ask_for_changes');

// 'Ask for changes'
$stateMachine->metadata('transition', 'ask_for_changes', 'title');
$stateMachine->metadata()->transition('ask_for_changes', 'title');

// null
$stateMachine->metadata('transition', 'ask_for_changes', 'invalid');
$stateMachine->metadata()->transition('ask_for_changes', 'invalid');

// 'default'
$stateMachine->metadata('transition', 'ask_for_changes', 'invalid', 'default');
$stateMachine->metadata()->transition('ask_for_changes', 'invalid', 'default');

调试命令

包含了一个用于调试图的 artisan 命令。它接受图的名称作为参数。如果没有传递参数，则会交互式地询问图名称。

$ php artisan winzou:state-machine:debug simple

+--------------------+-----------------------+
| Configured States: | Metadata:             |
+--------------------+-----------------------+
| new                |                       |
| pending_review     | title: Pending Review |
| awaiting_changes   |                       |
| accepted           |                       |
| published          |                       |
| rejected           |                       |
+--------------------+-----------------------+

+-----------------+------------------+------------------+
| Transition      | From(s)          | To               |
+-----------------+------------------+------------------+
| create          | new              | pending_review   |
+-----------------+------------------+------------------+
| ask_for_changes | pending_review   | awaiting_changes |
|                 | accepted         |                  |
+-----------------+------------------+------------------+
| cancel_changes  | awaiting_changes | pending_review   |
+-----------------+------------------+------------------+
| submit_changes  | awaiting_changes | pending_review   |
+-----------------+------------------+------------------+
| approve         | pending_review   | accepted         |
|                 | rejected         |                  |
+-----------------+------------------+------------------+
| publish         | accepted         | published        |
+-----------------+------------------+------------------+

+---------------------+--------------------+------------------------+--------+
| Guard Callbacks     | Satisfies          | Do                     | Args   |
+---------------------+--------------------+------------------------+--------+
| guard_on_submitting | On: submit_changes | MyClass::handle()      | object |
| guard_on_approving  | On: approve        | Gate::check("approve") |        |
+---------------------+--------------------+------------------------+--------+

+---------------------+-------------+-------------+-----------------------------+
| Before Callbacks    | Satisfies   | Do          | Args                        |
+---------------------+-------------+-------------+-----------------------------+
| log_before_approval | On: approve | Log::info() | "approving article", object |
+---------------------+-------------+-------------+-----------------------------+

+----------------------+--------------+------------------------------+---------------+
| After Callbacks      | Satisfies    | Do                           | Args          |
+----------------------+--------------+------------------------------+---------------+
| email_after_approval | To: accepted | SendApprovalMail::dispatch() | object, event |
+----------------------+--------------+------------------------------+---------------+

可视化命令

包含了一个用于生成给定图图像的 artisan 命令。它接受图的名称作为参数。这是从对应的 Symfony 包 https://github.com/MadMind/StateMachineVisualizationBundle 中获取的，所以所有荣誉都归原作者所有。

如果您想运行此命令，您需要安装 dot - 图形viz 包的一部分 (https://graphviz.cn/)。在您的 mac 上，这相当于已经运行了 brew install graphviz。

php artisan winzou:state-machine:visualize {graph? : A state machine graph} {--output=./graph.jpg} {--format=jpg} {--direction=TB} {--shape=circle} {--dot-path=/usr/local/bin/dot}

test

Eloquent 模型状态机特性

如果您想在模型内部直接与状态机交互，您可以安装 laravel-statable 包，由 iben12 提供。

此包允许您从模型中获取图，检查/应用转换，以及在数据库中记录状态历史。

更新日志

请参阅 更新日志 了解最近的变化。

测试

$ composer test

贡献

请参阅 贡献指南 获取详细信息。

安全

如果您发现任何安全问题，请通过电子邮件 info@sebdesign.eu 而不是使用问题跟踪器来报告。

鸣谢

许可

MIT 许可证 (MIT)。请参阅 许可文件 了解更多信息。