[ Laravel 5.2 ドキュメント ] サービス -- キュー

1. はじめに

Laravel キュー サービスは、さまざまなバックグラウンド キューに統合された API を提供します。キューを使用すると、時間のかかるタスク (電子メールの送信など) の実行を延期できるため、Web リクエストの速度が大幅に向上します。

1.1 設定

キュー設定ファイルは config/queue.php に保存されます。このファイルには、データベース、Beanstalkd、IronMQ、Amazon SQS、Redis、同期 (ローカル使用) ドライバーなど、フレームワークに付属するすべてのキュー ドライバーの接続構成が含まれています。キューに入れられたタスクを拒否するための null キュー ドライバーも含まれています。

1.2 キュードライバーの予備知識

データベース

データベースキュードライバーを使用するには、これを作成するマイグレーションを生成するためのタスクを保存するデータベーステーブルが必要です。テーブルを作成するには、アーティザン コマンド queue:table を実行します。移行が作成されたら、移行コマンドを使用して移行を実行します。

php artisan queue:tablephp artisan migrate

その他のキューの依存関係

必要な依存関係は次のとおりです。上記のキュードライバー用にインストールされます:

• Amazon SQS: aws/aws-sdk-php ~3.0
• Beanstalkd: pda/pheanstalk ~3.0
• Redis: predis/predis ~1.0

2. タスク クラスを作成します

2.1 タスク クラスを生成します

デフォルトでは、アプリケーションは app/Jobs ディレクトリに保存されます。 Artisan CLI を使用して新しいキュー タスクを生成できます:

php artisan make:job SendReminderEmail

このコマンドは app/Jobs ディレクトリに新しいクラスを生成します。このクラスは IlluminateContractsQueueShouldQueue インターフェイスを実装し、タスクが同期的に実行するのではなく、キューにプッシュします。

2.2 タスク クラスの構造

通常、タスク クラスには、キューがタスクを処理するときに実行されるハンドル メソッドのみが含まれています。 :

<?phpnamespace App\Jobs;use App\User;use App\Jobs\Job;use Illuminate\Contracts\Mail\Mailer;use Illuminate\Queue\SerializesModels;use Illuminate\Queue\InteractsWithQueue;use Illuminate\Contracts\Queue\ShouldQueue;class SendReminderEmail extends Job implements ShouldQueue{    use InteractsWithQueue, SerializesModels;    protected $user;    /**     * 创建一个新的任务实例     *     * @param  User  $user     * @return void     */    public function __construct(User $user)    {        $this->user = $user;    }    /**     * 执行任务     *     * @param  Mailer  $mailer     * @return void     */    public function handle(Mailer $mailer)    {        $mailer->send('emails.reminder', ['user' => $this->user], function ($m) {            //        });        $this->user->reminders()->create(...);    }}

この例では、Eloquent モデルをキュー タスクのコンストラクターに直接渡すことができることに注意してください。このタスクは SerializesModelstrait を使用するため、タスクの実行時に Eloquent モデルは正常にシリアル化および逆シリアル化されます。キュー タスクがコンストラクターで Eloquent モデルを受け取る場合、モデルの主キーのみがキューにシリアル化され、タスクが実際に実行されると、キュー システムはデータベースからモデル インスタンス全体を自動的に取得します。これはアプリケーションに対して完全に透過的であるため、Eloquent モデル インスタンス全体のシリアル化によって発生する問題を回避できます。

タスクがキューによって処理されるときにハンドル メソッドが呼び出されます。タスクのハンドル メソッドで依存関係の注入を実行できることに注意してください。 Laravel サービス コンテナは、これらの依存関係を自動的に挿入します。

エラー

タスクの処理中に例外がスローされた場合、タスクは自動的にキューに解放され、再度実行が試行されます。タスクは、試行回数がアプリケーションで許可されている最大数に達するまで解放され続けます。試行の最大数は、Artisan タスク queue:listen または queue:work の --tries スイッチによって定義されます。実行中のキュー リスナーの詳細については、以下を参照してください。

タスクを手動で解放する

タスクを手動で解放する場合、生成されたタスク クラスに付属する InteractsWithQueuetrait は、キュー タスクを解放するための release メソッドを提供します。このメソッドは 1 つのパラメーターを受け取ります。タスクの 2 つの実行間の待機時間は同じです:

public function handle(Mailer $mailer){    if (condition) {        $this->release(10);    }}

実行試行回数を確認します

前述のように、タスクの処理中に例外が発生した場合、タスクは自動的に解放されます。

public function handle(Mailer $mailer){    if ($this->attempts() > 3) {        //    }}

3. タスクをキューにプッシュします

デフォルトの Laravel コントローラーは app/Http/Controllers/Controller.php にあり、DispatchesJobstrait を使用します。このトレイトは、ディスパッチ メソッドなど、タスクをキューに簡単にプッシュできるメソッドをいくつか提供します。

<?phpnamespace App\Http\Controllers;use App\User;use Illuminate\Http\Request;use App\Jobs\SendReminderEmail;use App\Http\Controllers\Controller;class UserController extends Controller{    /**     * 发送提醒邮件到指定用户     *     * @param  Request  $request     * @param  int  $id     * @return Response     */    public function sendReminderEmail(Request $request, $id)    {        $user = User::findOrFail($id);        $this->dispatch(new SendReminderEmail($user));    }}

DispatchesJobs Trait

もちろん、場合によってはこのため、アプリケーション内の任意のクラスに DispatchesJobstrait を含めることで、ディスパッチ メソッドにアクセスできます。たとえば、この特性を使用するサンプル クラスを次に示します。 :

<?phpnamespace App;use Illuminate\Foundation\Bus\DispatchesJobs;class ExampleClass{    use DispatchesJobs;}

ディスパッチメソッド

代わりに、グローバルディスパッチメソッドを使用することもできます:

Route::get('/job', function () {    dispatch(new App\Jobs\PerformTask);    return 'Done!';});

タスクのキューを指定します

タスクの送信先のキューを指定することもできます。

タスクがプッシュされるさまざまなキューに基づいて、キューのタスクを「分類」し、複数のキューに割り当てられるワーカーの数に優先順位を付けることもできます。これは、キュー構成ファイルで定義されている別のキュー「接続」にタスクをプッシュするのではなく、単一の接続内の特定のキューにのみタスクをプッシュします。キューを指定するには、Laravel 独自の基本クラス AppJobsJob の IlluminateBusQueueabletrait によって提供されるタスク インスタンスの onQueue メソッドを使用します:

<?phpnamespace App\Http\Controllers;use App\User;use Illuminate\Http\Request;use App\Jobs\SendReminderEmail;use App\Http\Controllers\Controller;class UserController extends Controller{    /**     * 发送提醒邮件到指定用户     *     * @param  Request  $request     * @param  int  $id     * @return Response     */    public function sendReminderEmail(Request $request, $id)    {        $user = User::findOrFail($id);        $job = (new SendReminderEmail($user))->onQueue('emails');        $this->dispatch($job);    }}

3.1 延迟任务

有时候你可能想要延迟队列任务的执行。例如，你可能想要将一个注册15分钟后给消费者发送提醒邮件的任务放到队列中，可以通过使用任务类上的 delay方法来实现，该方法由 Illuminate\Bus\Queueabletrait提供：

<?phpnamespace App\Http\Controllers;use App\User;use Illuminate\Http\Request;use App\Jobs\SendReminderEmail;use App\Http\Controllers\Controller;class UserController extends Controller{    /**     * 发送提醒邮件到指定用户     *     * @param  Request  $request     * @param  int  $id     * @return Response     */    public function sendReminderEmail(Request $request, $id)    {        $user = User::findOrFail($id);        $job = (new SendReminderEmail($user))->delay(60);        $this->dispatch($job);    }}

在本例中，我们指定任务在队列中开始执行前延迟60秒。

注意：Amazon SQS服务最大延迟时间是15分钟。

3.2 任务事件

任务完成事件

Queue::after方法允许你在队列任务执行成功后注册一个要执行的回调函数。在该回调中我们可以添加日志、统计数据。例如，我们可以在Laravel内置的 AppServiceProvider中添加事件回调:

<?phpnamespace App\Providers;use Queue;use Illuminate\Support\ServiceProvider;class AppServiceProvider extends ServiceProvider{    /**     * Bootstrap any application services.     *     * @return void     */    public function boot()    {        Queue::after(function ($connection, $job, $data) {            //        });    }    /**     * Register the service provider.     *     * @return void     */    public function register()    {        //    }}

4、运行队列监听器

启动任务监听器

Laravel 包含了一个 Artisan 命令用来运行被推送到队列的新任务。你可以使用 queue:listen命令运行监听器：

php artisan queue:listen

还可以指定监听器使用哪个队列连接：

php artisan queue:listen connection

注意一旦任务开始后，将会持续运行直到手动停止。你可以使用一个过程监视器如Supervisor来确保队列监听器没有停止运行。

队列 优先级

你可以传递逗号分隔的队列连接列表到 listen任务来设置队列优先级：

php artisan queue:listen --queue=high,low

在本例中， high队列上的任务总是在从 low队列移动任务之前被处理。

指定任务超时参数

你还可以设置每个任务允许运行的最大时间（以秒为单位）：

php artisan queue:listen --timeout=60

指定队列睡眠时间

此外，可以指定轮询新任务之前的等待时间（以秒为单位）：

php artisan queue:listen --sleep=5

需要注意的是队列只会在队列上没有任务时“睡眠”，如果存在多个有效任务，该队列会持续运行，从不睡眠。

4.1 Supervisor配置

Supervisor为Linux操作系统提供的进程监视器，将会在失败时自动重启 queue:listen或 queue:work命令，要在Ubuntu上安装Supervisor，使用如下命令：

sudo apt-get install supervisor

Supervisor配置文件通常存放在 /etc/supervisor/conf.d目录，在该目录中，可以创建多个配置文件指示Supervisor如何监视进程，例如，让我们创建一个开启并监视 queue:work进程的 laravel-worker.conf文件：

[program:laravel-worker]process_name=%(program_name)s_%(process_num)02dcommand=php /home/forge/app.com/artisan queue:work sqs --sleep=3 --tries=3 --daemonautostart=trueautorestart=trueuser=forgenumprocs=8redirect_stderr=truestdout_logfile=/home/forge/app.com/worker.log

在本例中， numprocs指令让Supervisor运行8个 queue:work进程并监视它们，如果失败的话自动重启。配置文件创建好了之后，可以使用如下命令更新Supervisor配置并开启进程：

sudo supervisord -c /etc/supervisord.confsudo supervisorctl -c /etc/supervisor/supervisord.confsudo supervisorctl rereadsudo supervisorctl updatesudo supervisorctl start laravel-worker:*

要了解更多关于Supervisor的使用和配置，查看 Supervisor文档。此外，还可以使用Laravel Forge从web接口方便地自动配置和管理Supervisor配置。

4.2 后台队列监听器

Artisan命令 queue:work包含一个 --daemon选项来强制队列worker持续处理任务而不必重新启动框架。相较于 queue:listen命令该命令对CPU的使用有明显降低：

php artisan queue:work connection --daemonphp artisan queue:work connection --daemon --sleep=3php artisan queue:work connection --daemon --sleep=3 --tries=3

正如你所看到的， queue:work任务支持大多数 queue:listen中有效的选项。你可以使用 php artisan help queue:work任务来查看所有有效选项。

后台队列监听器编码考虑

后台队列worker在处理每个任务时不重启框架，因此，你要在任务完成之前释放资源，举个例子，如果你在使用GD库操作图片，那么就在完成时使用 imagedestroy释放内存。

类似的，数据库连接应该在后台长时间运行完成后断开，你可以使用 DB::reconnect方法确保获取了一个新的连接。

4.3 部署后台队列监听器

由于后台队列worker是常驻进程，不重启的话不会应用代码中的更改，所以，最简单的部署后台队列worker的方式是使用部署脚本重启所有worker，你可以通过在部署脚本中包含如下命令重启所有worker：

php artisan queue:restart

该命令会告诉所有队列worker在完成当前任务处理后重启以便没有任务被遗漏。

注意：这个命令依赖于缓存系统重启进度表，默认情况下，APC在CLI任务中无法正常工作，如果你在使用APC，需要在APC配置中添加 apc.enable_cli=1。

5、处理失败任务

由于事情并不总是按照计划发展，有时候你的队列任务会失败。别担心，它发生在我们大多数人身上！Laravel包含了一个方便的方式来指定任务最大尝试执行次数，任务执行次数达到最大限制后，会被插入到 failed_jobs表，失败任务的名字可以通过配置文件 config/queue.php来配置。

要创建一个 failed_jobs表的迁移，可以使用 queue:failed-table命令：

php artisan queue:failed-table

运行队列监听器的时候，可以在 queue:listen命令上使用 --tries开关来指定任务最大可尝试执行次数：

php artisan queue:listen connection-name --tries=3

5.1 失败任务事件

如果你想要注册一个队列任务失败时被调用的事件，可以使用 Queue::failing方法，该事件通过邮件或 HipChat通知团队。举个例子，我么可以在Laravel自带的 AppServiceProvider中附件一个回调到该事件：

<?phpnamespace App\Providers;use Queue;use Illuminate\Support\ServiceProvider;class AppServiceProvider extends ServiceProvider{    /**     * 启动应用服务     *     * @return void     */    public function boot()    {        Queue::failing(function ($connection, $job, $data) {            // Notify team of failing job...        });    }    /**     * 注册服务提供者     *     * @return void     */    public function register()    {        //    }}

任务类的失败方法

想要更加细粒度的控制，可以在队列任务类上直接定义 failed方法，从而允许你在失败发生时执行指定动作：

<?phpnamespace App\Jobs;use App\Jobs\Job;use Illuminate\Contracts\Mail\Mailer;use Illuminate\Queue\SerializesModels;use Illuminate\Queue\InteractsWithQueue;use Illuminate\Contracts\Bus\SelfHandling;use Illuminate\Contracts\Queue\ShouldQueue;class SendReminderEmail extends Job implements SelfHandling, ShouldQueue{    use InteractsWithQueue, SerializesModels;    /**     * 执行任务     *     * @param  Mailer  $mailer     * @return void     */    public function handle(Mailer $mailer)    {        //    }    /**     * 处理失败任务     *     * @return void     */    public function failed()    {        // Called when the job is failing...    }}

5.2 重试失败任务

要查看已插入到 failed_jobs数据表中的所有失败任务，可以使用Artisan命令 queue:failed：

php artisan queue:failed

该命令将会列出任务ID，连接，对列和失败时间，任务ID可用于重试失败任务，例如，要重试一个ID为5的失败任务，要用到下面的命令：

php artisan queue:retry 5

要重试所有失败任务，使用如下命令即可：

php artisan queue:retry all

如果你要删除一个失败任务，可以使用 queue:forget命令：

php artisan queue:forget 5

要删除所有失败任务，可以使用 queue:flush命令：

php artisan queue:flush