README

一个用于处理带有事件触发功能简单动作的包。

Laravel Actions 是类似作业的简单类，不与队列交互。当你有一些需要重复使用的简单功能时，动作非常有用。

但为什么你想使用动作呢？当你想要将一些小段代码提取到可测试的小类中时，动作非常出色。当不需要或不需要这种功能时，动作也可以替代排队作业，或者当你需要立即看到代码的结果时。

但真正的力量在于事件处理。

该包在动作执行过程中公开了两个事件

在动作开始之前
在动作完成后

这里的特殊之处在于，你可以告诉动作你希望触发哪些事件！

要求

安装

composer require kirschbaum-development/laravel-actions

创建和准备动作

使用 artisan 命令创建新的动作

php artisan make:action ChuckNorris

这将创建一个新的动作类在 app/Actions/ChuckNorris.php。你当然可以自由地将其移动到任何你想去的地方。只需确保更新命名空间即可！

有两个公共属性供你的事件使用：$before 和 $after。你可以使用其中之一或两个，如果你在动作类中不使用它们，也可以删除它们。

 /**
  * Event to dispatch before action starts.
  *
  * @var string
  */
 public $before = ChuckNorrisWillBlowYourMind::class;

 /**
  * Event to dispatch after action completes.
  *
  * @var string
  */
 public $after = ChuckNorrisBlewYourMind::class;

接下来，在你的 __construct() 方法中放置所需的参数，并在 __invoke() 方法中放置你的动作代码。你可以从可调用的方法中返回你可能需要的东西。现在我们可以使用动作了！

/**
 * Create a new action instance.
 *
 * @return void
 */
public function __construct()
{
    // Pass any arguments you need.
}

/**
 * Execute the action.
 *
 * @return mixed
 */
public function __invoke()
{
    // Handle your action here.
}

用法

我们可以以两种不同的方式调用我们刚刚创建的动作。

从动作

只要类使用 CanAct 特性，我们就可以在动作本身上调用三个方法之一。

ChuckNorris::act($data);
ChuckNorris::actWhen($isChuckNorrisMighty, $data);
ChuckNorris::actUnless($isChuckNorrisPuny, $data);

$data 被传递到动作的构造函数中。你可以根据你的用例传递所需数量的参数。

后两个方法，actWhen 和 actUnless 需要一个条件作为第一个变量。这些方法的工作方式与 Laravel 的其他方法类似，如 throw_if() 和 throw_unless()。最后，你可以在条件之后传递所需数量的参数给你的动作。

外观

该包还有一个外观。这是语法

use Kirschbaum\Actions\Facades\Action;

Action::act(ChuckNorris::class, $data);
Action::actWhen($isChuckNorrisMighty, ChuckNorris::class, $data);
Action::actUnless($isChuckNorrisPuny, ChuckNorris::class, $data);

用法几乎与在上一节中提到的直接调用动作方法相同。这里的优点是，你可以轻松地使用 Action::shouldReceive('act')、Action::shouldReceive('actWhen') 或 Action::shouldReceive('actUnless') 来测试动作。

助手

该包还有一些方便的助手来让 Chuck 动起来。这是语法

act(ChuckNorris::class, $data);
act_when($isChuckNorrisMighty, ChuckNorris::class, $data);
act_unless($isChuckNorrisPuny, ChuckNorris::class, $data);

依赖注入

你甚至可以在应用程序内部将动作注入为依赖项！

use Kirschbaum\Actions\Action;

public function index (Action $action)
{
    $action->act(ChuckNorris::class, $data);
    $action->actWhen($isChuckNorrisMighty, ChuckNorris::class, $data);
    $action->actUnless($isChuckNorrisPuny, ChuckNorris::class, $data);
}

处理失败

我们都知道 Chuck Norris 不会让我们失望，但他不是唯一使用这个... 使用动作处理失败非常简单。默认情况下，由你的动作类抛出的任何异常都会由 Laravel 的异常处理器处理。如果你想在失败时实现自己的逻辑，请向你的动作添加一个 failed() 方法。就这么简单！你也可以选择从你的 failed() 方法返回数据。

/**
 * Handle failure of the action.
 *
 * @throws Throwable
 *
 * @return mixed
 */
public function failed(Throwable $exception)
{
    event(new VanDammeFailedEvent);
}

Hashtag #BAM!

自定义异常

处理失败的一种方法是让Action自己抛出异常。如果你不需要编写自己的failed()方法带来的额外开销，可以直接让Action抛出自定义异常。这就像只是定义从Action中抛出的异常那么简单。

/**
 * Event to dispatch if action throws an exception.
 *
 * @var string
 */
public $exception = SeagalFailedException::class;

自动发现和配置

默认情况下，Action会被自动发现并绑定到Laravel的容器中，这使得测试Action变得更容易。如果你将Action放在除了app/Actions之外的路径，需要添加自定义路径，请确保发布配置。

php artisan vendor:publish --tag laravel-actions

如果你想要禁用自动发现，发布配置并从paths键返回一个空数组。

return [
    'paths' => [],
];

测试

无需担心，测试这一切非常简单。内置了两种测试方法。

测试门面

如果你使用门面来实现Action，可以直接从门面使用标准的shouldReceive()方法。

use Kirschbaum\Actions\Facades\Action;

Action::shouldReceive('act')
    ->once()
    ->andReturnTrue();

模拟

如果你使用助手函数、CanAct特质或依赖注入，可以使用Laravel的模拟工具轻松模拟Action类。

use Kirschbaum\Actions\Action;

$this->mock(Action::class, function ($mock) {
    $mock->shouldReceive('act')
        ->once()
        ->andReturnTrue();
});

由于Action默认绑定到Laravel的容器中，你也可以测试特定的Action。

use App\Actions\ChuckNorris;

$this->mock(ChuckNorris::class, function ($mock) {
    $mock->shouldReceive('act')
        ->once()
        ->andReturnTrue();
});

最后思考

如果你出于某种原因不想使用酷的事件系统、门面、模拟等，那也可以。只需像这样调用Action

new ChuckNorris($data);

这将绕过所有魔法并自动调用invoke方法，让Chuck做他的事情，但为什么？ ;)

更新日志

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

贡献

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

安全性

如果你发现任何与安全相关的问题，请通过电子邮件brandon@kirschbaumdevelopment.com或nathan@kirschbaumdevelopment.com联系，而不是使用问题跟踪器。

鸣谢

Brandon Ferens
部分灵感来源于Luke Downing的Laracon Online Winter '22 演讲。

赞助

此包的开发由Kirschbaum赞助，Kirschbaum是一家以解决问题、团队建设和社区为中心的开发者驱动型公司。了解更多关于我们或加入我们！

许可证

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

kirchbaum-development/laravel-actions

维护者

详细信息