[译]Laravel 5.0 之命令及处理程序

本文译自 Matt Stauffer系列文章.


本文中涉及的新功能都是关于 Commands 的,这些特性在 Laravel 旧版本中已经有了,但是在 Laravel 5.0 中变得更加好用了。

本文中将会用到例子来自于我正在开发的一个叫做 SaveMyProposals 的新应用。

什么是 Command, Command handler 和 Command bus?

Shawn McCool 的这篇文章 中,你可以深入了解 command, command handler, command bus 的概念。但总的来说:

Command 是一个代表信息的简单对象。它只包含你打算做某件事时需要用到的信息。在我们接下来的例子中,它就是 “复制谈话命令(Duplicate Talk Command)”, 任何时候当用户要复制一条谈话建议时,我们的系统就会调用它。 这个 “重复谈话命令” 会包含复制一个谈话所需要的全部属性集——比如一个序列化的 Talk 对象或者是 TaldId.

Command Handler 则是用于对 Command 做出响应的一个类。Command 可以在一个或多个 Handlers 之间传递, 每个 Handler 从 Command 中取出重要的信息并做某些操作来响应。

Command bus 是一套用于调度 Commands 的系统。它把 commands 与对应的 Handlers 进行匹配,并使它们能够一起工作。一般情况下,人们需要编写自己的 command bus, 但 Laravel 内置了一个开箱即用的 Command bus, 所以至少在本文涉及的范围内我们不用担心这个问题。

在 Laravel 中使用 Command

在开始介绍 Laravel 5.0 中使用 Command 的整个结构之前,我们先看看最终的用例是怎样的。假设一个用户访问了系统的某个路由,比如 savemyproposals.com/talks/12345/duplicate, 该路由被解析到 TalkController@duplicate(12345).

下面是处理这个请求的路由和方法:

// Http\Controllers\TalkController
...
    public function duplicate($talkId)
    {
        $talk = Talk::findOrFail($talkId);

        $this->dispatch(new DuplicateTalkCommand($talk));

        // 取决于具体的实现,这两行代码也可能简化为一行代码:
        // $this->dispatch(new DuplicateTalkCommand($talkId));
    }

接下来是 Command 的代码:

// Commands\DuplicateTalkCommand
...

class DuplicateTalkCommand extends Command
{
    public $talk;

    public function __construct(Talk $talk)
    {
        $this->talk = $talk;
    }
}

然后是 Command handler:

// Handlers\Commands\DuplicateTalkCommandHandler
...

class DuplicateTalkCommandHandler
{
    public function handle(DuplicateTalkCommand $command)
    {
        // 对 $command 变量进行某些操作
        dd($command);
    }
}

就如上面的代码所展示的,控制器通过一些必要的信息创建了一个 DuplicateTalkCommand 对象,通过内置的 command bus dispatcher 对齐进行调度,于是该命令的处理程序自动对其进行处理。

体系结构

接下来,我们先来看看这些命令和处理程序存放在什么位置,然后再说说如何生成它们。

文件夹

在 Laravel 5.0 的应用框架中,app/ 目录下有两个新的文件夹:CommandsHandlers, Handlers 目录下还有两个子目录:CommandsEvents(这个目录说明我们还可以期待事件处理的特性).

app/
    Commands/
    Handlers/
        Commands/
        Events/

相信看到目录结构你就能猜到,Commands 的代码存放在 app/Commands 目录下,而 Command handlers 则存放在 app/Handlers/Commands 目录下—— Handler 的文件名与其对应的 Command 保持一致,但是要加上 Handler 后缀。

Artisan

非常值得庆幸的是,你不用自己动手来创建 Command 和 Command Handler。新版本提供了一个全新的 Artisan 生成工具,通过它可以快速生成这些文件:

$ php artisan make:command DuplicateTalkCommand

默认情况下,这条命令会生成一个自处理的命令(不生成单独的 Command handler),并且该命令不添加到队列。加上 --handler 参数可以同时生成 handler, 加上 --queued 参数可以将其加入到队列。

执行这个 artisan 命令会生成两个文件: 命令文件(app/Commands/DuplicateTalkCommand.php) 和 处理程序文件(app/Handlers/Commands/DuplicateTalkCommandHandler.php) (假设使用了 --handler 参数),并且生成的处理程序中的 handle 方法会自动加上与其匹配的命令的类型约束。

基本工作流程

综上所述,要创建一个新的 DuplicateTalkCommand, 你需要执行以下工作:

  1. php artisan make:command DuplicateTalkCommand
  2. 编辑 DuplicateTalkCommand, 增加一个 public 属性 $talk 并在构造函数中初始化这个属性。
  3. 编辑 DuplicateTalkCommandHandler, 在 handle() 方法中编写具体代码,完成你需要执行的操作。
  4. 在控制器或者 Artisan 命令中调度(调用)这个命令。

队列

把命令加入队列

如果希望某个命令在每次被调用时加入到队列中以便异步执行,你需要做的是让该命令实现 ShouldBeQueued 接口。 Laravel 会发现这个接口并把其加入队列等候执行,而不是立即执行。

...
class DuplicateTalkCommand extends Command implements ShouldBeQueued
{
    //...
}

InteractsWithQueue trait

在你的 Command 类中加上这个 trait, 会让你的 Command 具有在以前版本中用惯了的队列命令(queue commands)所具有的全部特性:$command->release(), $command->delete(), $command->attempts() 等等。

...
class DuplicateTalkCommand extends Command implements ShouldBeQueued, InteractsWithQueue
{
    //...
}

SerializesModels trait

如果你传入一个 Eloquent 模型作为属性,就像前面的例子中那样,并且希望命令放入队列中执行而不是同步执行,那么必须要考虑到 Eloquent 模型的序列化,这可能会给你带来一些麻烦。不过在 Laravel 5.0 版本中,你可以给你的 Command 加一个 名为 SerializesModels 的 trait 来解决这个问题。方法很简单,在类的代码块顶部加上即可:

...
class DuplicateTalkCommand extends Command implements ShouldBeQueued
{ 
    use SerializesModels;
    // ...
}

Dispatcher

DispatchesCommands Trait

你可能注意到,在前面的例子中,我们可以直接在控制器中使用 $this->dispatch() 方法。这是控制器的一个语法糖。这个语法糖实际上是通过名为 DispathesCommands 的 trait 来实现的。你可以在控制器之外的任何地方使用这个 trait.

比如,你希望某个服务类可以在方法中使用 $this->dispatch(), 你只要在你的服务类的代码块顶部使用 DispatchesCommands 这个 trait 即可:

...
class MyServiceClass {

    use DispatchesCommands;

    //...
}

注入 bus

如果你希望更直接、更清楚地调用 Command bus 而不是借助于 Laravel 系统提供的 trait, 你可以直接向你的类的构造函数或者是方法注入 Illuminate\Contracts\Bus\Dispatcher 实例(参见 Laravel 5.0 之方法注入)。

...
    public function __construct(\Illuminate\Contracts\Bus\Dispatcher $bus)
    {
        $this->bus = $bus;
    }

    public function doSomething()
    {
        $this->bus->dispatch(new Command);
    }

dispatchFrom(command::class, $request 或任何 arrayAccessible 对象)

在之前的例子中,我们已经看到了调用命令的最简单方式,就是 $bus->dispatch(new Command(params...)). 但有时候由于新建命令的参数列表变得越来越大——比如,当你的命令用于来处理表单输入的时候:

...
class CreateTalkCommand extends Command
{
    public function __construct($title, $description, $outline, $organizer_notes, $length, $type, $level) {
        // ...
    }
}

这时,如果还用之前的方式来实例化命令,代码会变得很难看:

$this->dispatch(new CreateTalkCommand($input['title'], $input['description'],
        $input['outline'], $input['organizer_notes'], $input['length'],
        $input['type'], $input['level']));

通常我们的表单请求会传递与属性相同 key 的数组,从数组或者请求对象中获得具体的值。幸亏 Laravel 5.0 有针对这种情况的解决方案:

$this->dispatch('NameOfCommand', $objectThatImplementsPHPArrayAccessible);

因此我们可以用下面的代码替换上面那长长的一串:

$this->dispatchFrom(CreateTalkCommand::class, $input);

或者这样:

public function doSomethingInController(Request $request)
    {
        $this->dispatchFrom(CreateTalkCommand::class, $request);
        // ...
    }

Laravel 会自动在传入的数组或者 arrayAccessible 对象中去寻找与属性名相同的 key, 取出对应的值来调用命令的构造函数。

自处理命令

如果你嫌每个命令都要创建一个 Command 类和一个 Command handler 类太麻烦的话,你可以创建一个“自处理”的 Command. 这种情况下 Command 只有单一的处理程序,且该处理程序就是 Command 自己。要让一个 Command 变成自处理,只需要给该 command 类加一个 handle() 方法,并让它实现 SelfHandling 接口:

...
class DuplicateTalkCommand extends Command implements SelfHandling
{
    //...
    public function handle()
    {
        //...
    }

其它注意事项

  • 命令处理程序会由 IOC 容器进行解析,因此你可以注入 repositories, service classes 或者任何其它类型到你的命令处理程序的构造函数中,然后在 handle() 方法中调用它们。
  • 几乎所有相关的 trait 和 接口都在 Illuminate\Contracts\Bus 或者 Illuminate\Contracts\Queue 命名空间下。比如,Illuminate\Contracts\Bus\SelfHandling.
  • 如果你的命令是放入队列执行,不需要在处理程序的最后执行 $command->delete() 方法。只要你的处理程序没有抛出任何异常,Laravel 会假定它已经正确完成,并自动将其从队列中移除。

写在最后

就这么多了,如果我遗漏了什么,或者某个问题讲得不够清楚,请让我知道。本文涉及到的点还有一些需要补充和替换的地方。暂时来说,我希望本文可以帮助你了解新版 Laravel 中的 Command 的运行机制。此外,Taylor 在 Laracasts 上的视频 涵盖了本文的全部内容并且讲得更多。

               

[译]Laravel 5.0 之命令及处理程序》上有6条评论

  1. q

    用dispatchFrom传入request得不到参数呢?楼主测试了吗

  2. 不爽

    这种不接地气的文章,真的是白看了,作用是什么也没简单阐述,连个最简单通俗易懂的demo都没,还怎么让Laravel在中国流行!

  3. Pingback引用通告: [译]Laravel 5.0 之事件及处理程序 - PHP - 裁纸刀下

  4. 云袭

    博主你好,我是 phphub 的管理员,感谢你的辛苦翻译,质量都特别高,想请问下能否转载至 phphub,我会指明出处,并且做一个引导帖,把这几篇都放在一起。

评论已关闭。