README

动作

动作类是将业务逻辑从应用程序的其他部分隔离出来的模式。这使得测试业务逻辑变得更加容易，并提供了可移植性：您可以在多个上下文中使用相同的动作类，这有助于减少代码库的重复。

此包提供创建易于与您的PHP应用程序集成的动作类的基石。

灵感

这个想法在我的脑海中已经存在了一段时间。然而，这些博客文章真正帮助我形成了关于动作类应该如何工作的想法，并激发了我创建此包的灵感

安装

使用Composer安装此库

$ composer require stagerightlabs/actions

说明

此库提供抽象的Action类，您可以通过扩展它来创建自己的动作类。您需要做的就是提供一个包含您的业务逻辑的handle方法。例如

<?php

namespace App\Actions;

use StageRightLabs\Actions\Action;

class MyCoolAction extends Action
{
  public function handle($input = [])
  {
    // business logic goes here...

    return $this->complete('Hooray, it worked!');
  }
}

要在您的应用程序中使用此类，您可以调用静态的execute()方法

<?php

namespace App\Http\Controllers;

use App\Actions\MyCoolAction;

class Controller
{
  public function post()
  {
    $action = MyCoolAction::execute();

    if ($action->failed()) {
      // send an alert
      return;
    }

    // do something else
    return;
  }
}

请注意我们如何根据动作的结果生成响应。

输入

很少会有业务逻辑可以在没有某种输入的情况下执行。我们可以通过提供包含数据的关联数组来为我们的动作类提供输入。为了确保动作在任务运行之前一切就绪，类将在任务运行之前验证输入数组的键。

<?php

namespace App\Actions;

use StageRightLabs\Actions\Action;

class UserCreationAction extends Action
{
  public function handle($input = [])
  {
    // User is created here...

    return $this->complete();
  }

  public function required()
  {
    return [
      'username',
      'email',
    ]
  }

  public function optional()
  {
    return [
      'timezone'
    ]
  }
}

我们使用required()和optional()方法来告诉动作预期的输入键。如果缺少必需的键，动作将在执行之前失败。如果提供了任何未定义为必需或可选的输入键，动作将失败。请注意，此验证仅针对数组键执行；如果提供了键但包含假值，动作仍将继续。

此验证步骤的目标是为未来的开发者提供关于您的动作类如何工作以及它们需要哪些输入的清晰度。

完成状态

在执行业务逻辑的过程中，我们可能会决定动作需要失败或已完成。使用fail()和complete()方法设置动作的状态并停止进一步的执行

public function handle($input = [])
{
  if (is_null($user)) {
    return $this->fail('There was a problem creating your account.');
  }

  return $this->complete('Your new account has been created.');
}

消息是可选的。可以这样访问

$action = MyCoolAction::execute();

if ($action->failed()) {
  $this->sendAlert($action->getMessage());
  return;
}

输出

通常您会发现动作会产生您希望在其他地方可用的工件。为了保留这些工件，请将它们分配到动作中的公共类属性。这使得动作类本身可以表现为数据传输对象

<?php

namespace App\Actions;

use StageRightLabs\Actions\Action;

class UserCreationAction extends Action
{
  public $user;

  public function handle($input = [])
  {
    $this->user = User::create($input);

    return $this->complete();
  }
}

执行完成后，您可以访问这些工件

$action = MyCoolAction::execute();

if ($action->failed()) {
  $this->sendAlert($action->getMessage());
  return;
}

$user = $action->user;

类构造函数

如果您想在动作类上定义构造函数以允许依赖注入，那么您将无法再调用静态的execute()方法。然而，您可以从常规对象上下文中调用它

$action = new MyCoolAction(new SomeDependency);
$action = $action->execute();

API

execute($input)：用于触发动作的静态方法。$input数组应包含动作执行所需的一切。
handle($input)：在这里定义动作将执行的工作。如果动作类已实例化，您可以直接调用此方法来触发动作，但这将跳过输入键验证。
required()：使用此方法定义一个数组，其中包含您操作所需的输入键。
optional()：使用此方法定义一个数组，其中包含您操作允许但不必需的输入键。
complete($optionalMessage)：将操作标记为完成并停止执行。您可以可选地提供一条完成消息。
fail($optionalMessage)：将操作标记为失败并停止执行。您可以可选地提供一条失败消息。
completed()：检查操作完成状态。如果操作已完成，则返回true，如果没有完成，则返回false。
failed()：检查操作失败状态。如果操作失败，则返回true，如果没有失败，则返回false。
getMessage()：检索在调用complete()或fail()时设置的消息。

stagerightlabs / actions

维护者

详情

README

动作

灵感

安装

说明

输入

完成状态

输出

类构造函数

API