Laravel 5.0 キュー

設定Configuration

Laravelのキューコンポーネントは、様々なキューサービス共通のAPIを提供しています。キューによりメール送信のような時間を費やす処理を夜中まで遅らせることが可能です。これによりアプリケーションのリクエストを徹底的に引き上げることができます。The Laravel Queue component provides a unified API across a variety of different queue services. Queues allow you to defer the processing of a time consuming task, such as sending an e-mail, until a later time, thus drastically speeding up the web requests to your application.

キューの設定ファイルはconfig/queue.phpです。このファイルには、フレームワークに含まれているそれぞれのドライバーへの接続設定があります。それには、データベース、Beanstalkd、IronMQ、Amazon SQS、Redis、null、同期（ローカル用途）ドライバーが含まれています。nullキュードライバーはキューされたジョブが実行されないように、破棄するだけです。The queue configuration file is stored in config/queue.php. In this file you will find connection configurations for each of the queue drivers that are included with the framework, which includes a database, Beanstalkd[http://kr.github.com/beanstalkd], IronMQ[http://iron.io], Amazon SQS[http://aws.amazon.com/sqs], Redis[http://redis.io], null, and synchronous (for local use) driver. The null queue driver simply discards queued jobs so they are never run.

データベースキューテーブルQueue Database Table

databaseキュードライバーを使用するには、ジョブを記録するためのデータベーステーブルが必要です。このテーブルを作成するマイグレーションは、queue:table Artisanコマンドにより生成できます。In order to use the database queue driver, you will need a database table to hold the jobs. To generate a migration to create this table, run the queue:table Artisan command:

php artisan queue:table

キューに必要なパッケージOther Queue Dependencies

前記のキュードライバーを使用するには、以下の対応するパッケージをcomposer.jsonに付け加えることが必要です。The following dependencies are needed for the listed queue drivers:

• Amazon SQS: aws/aws-sdk-phpAmazon SQS: aws/aws-sdk-php
• Beanstalkd: pda/pheanstalk ~3.0Beanstalkd: pda/pheanstalk ~3.0
• IronMQ: iron-io/iron_mq ~1.5IronMQ: iron-io/iron_mq ~1.5
• Redis: predis/predis ~1.0Redis: predis/predis ~1.0

基本的な使用法Basic Usage

キューへジョブ登録Pushing A Job Onto The Queue

アプリケーションにキュー投入できる全ジョブはApp\Commandsディレクトリーに保存します。新しいキュー投入コマンドを生成するには、Artisan CLIコマンドを使用します。All of the queueable jobs for your application are stored in the App\Commands directory. You may generate a new queued command using the Artisan CLI:

php artisan make:command SendEmail --queued

新しいジョブをキューに投入するには、Queue::pushメソッドを使用します。To push a new job onto the queue, use the Queue::push method:

Queue::push(new SendEmail($message));

注目： この例では、Queueファサードを直接使用しています。しかし、通常キューコマンドをディスパッチするには、コマンドバスの方が好まれます。このページでは、以降も続けてQueueファサードを使用しますが、アプリケーション上でキューと同期コマンドの両方を起動することができますので、コマンドバスにも習熟してください。Note: In this example, we are using the Queue facade directly; however, typically you would dispatch queued command via the Command Bus[/docs/{{version}}/bus]. We will continue to use the Queue facade throughout this page; however, familiarize with the command bus as well, since it is used to dispatch both queued and synchronous commands for your application.

make:command Artisanコマンドのデフォルトは、「自己処理」コマンドを生成します。つまり、handleメソッドがコマンド自身へ含まれています。このメソッドはキューにより、ジョブが実行されるときに呼び出されます。handleメソッドには必要な依存をタイプヒントで指定でき、サービスコンテナが自動的に注入します。By default, the make:command Artisan command generates a "self-handling" command, meaning a handle method is added to the command itself. This method will be called when the job is executed by the queue. You may type-hint any dependencies you need on the handle method and the service container[/docs/{{version}}/container] will automatically inject them:

public function handle(UserRepository $users)
{
	//
}

コマンドから独立したハンドラークラスを持たせたい場合は、--handlerフラッグをmake:commandコマンドに付けます。If you would like your command to have a separate handler class, you should add the --handler flag to the make:command command:

php artisan make:command SendEmail --queued --handler

生成されるハンドラーは、App\Handlers\Commandsに置かれ、IoCコンテナにより依存解決されます。The generated handler will be placed in App\Handlers\Commands and will be resolved out of the IoC container.

ジョブのキューを指定Specifying The Queue / Tube For A Job

どのキューにジョブを登録するのかを指定することもできます。You may also specify the queue / tube a job should be sent to:

Queue::pushOn('emails', new SendEmail($message));

同一データ本体の複数ジョブ投入Passing The Same Payload To Multiple Jobs

同じデーターを複数のキュージョブに送る必要がある場合は、Queue::bulkメソッドを使用して下さい。If you need to pass the same data to several queue jobs, you may use the Queue::bulk method:

Queue::bulk([new SendEmail($message), new AnotherCommand]);

ジョブ実行の遅延Delaying The Execution Of A Job

キュージョブの実行を遅らせたい場合もあるでしょう。例えば、サインアップの１５分後に顧客へメールを送信するジョブをキューしたい場合などです。この場合、Queue::laterメソッドを使用して下さい。Sometimes you may wish to delay the execution of a queued job. For instance, you may wish to queue a job that sends a customer an e-mail 15 minutes after sign-up. You can accomplish this using the Queue::later method:

$date = Carbon::now()->addMinutes(15);

Queue::later($date, new SendEmail($message));

この例の中で、ジョブに希望する遅延実行時間を指定するために、Carbonライブラリーを使用しています。もしくは、整数で遅らせたい秒数を渡すこともできます。In this example, we're using the Carbon[https://github.com/briannesbitt/Carbon] date library to specify the delay we wish to assign to the job. Alternatively, you may pass the number of seconds you wish to delay as an integer.

注目： Amazon SQSサービスには、遅延９００秒（１５分）という制限があります。Note: The Amazon SQS service has a delay limit of 900 seconds (15 minutes).

キューとEloquentモデルQueues And Eloquent Models

もし、キュージョブがコンストラクターにEloquentモデルを受け付ける場合、そのモデルのIDだけがキューへシリアライズされます。実際にそのジョブが処理される時に、キューシステムはデータベースからモデルの完全なインスタンスを自動的に再取得します。これにより、Eloquentのモデルインスタンスを完全にシリアライズすると持ち上がる問題を防ぐことができ、アプリケーションに対する完全な透過性も保てます。If your queued job accepts an Eloquent model in its constructor, only the identifier for the model will be serialized onto the queue. When the job is actually handled, the queue system will automatically re-retrieve the full model instance from the database. It's all totally transparent to your application and prevents issues that can arise from serializing full Eloquent model instances.

処理済みのジョブの削除Deleting A Processed Job

ジョブを処理し終えた時、キューから削除する必要があります。ジョブの実行中に例外が投げられなければ、これは自動的に行われます。Once you have processed a job, it must be deleted from the queue. If no exception is thrown during the execution of your job, this will be done automatically.

ジョブを自分でdeleteやreleaseしたければ、Illuminate\Queue\InteractsWithQueueトレイトが提供するreleaseとdeleteメソッドで行えます。releaseメソッドは引数をひとつだけ取り、再度実行するまでに待つ秒数を指定します。If you would like to delete or release the job manually, the Illuminate\Queue\InteractsWithQueue trait provides access to the queue job release and delete methods. The release method accepts a single value: the number of seconds you wish to wait until the job is made available again.

public function handle(SendEmail $command)
{
	if (true)
	{
		$this->release(30);
	}
}

ジョブのキュー再投入Releasing A Job Back Onto The Queue

処理中に例外が投げられると、再実行できるよう自動的にキューに戻されます。アプリケーションで許可されている最高実行回数まで、そのジョブは繰り返されます。最高実行回数は、queue:listenとqueue:work Artisanコマンドへ、--triesスイッチにより指定されます。IF an exception is thrown while the job is being processed, it will automatically be released back onto the queue so it may be attempted again. The job will continue to be released until it has been attempted the maximum number of times allowed by your application. The number of maximum attempts is defined by the --tries switch used on the queue:listen or queue:work Artisan commands.

実行回数の取得Checking The Number Of Run Attempts

ジョブの処理中に例外が起きた場合、そのジョブは自動的にキューに再登録されます。そのジョブを実行しようとした試行回数をattemptsメソッドで調べることができます。If an exception occurs while the job is being processed, it will automatically be released back onto the queue. You may check the number of attempts that have been made to run the job using the attempts method:

if ($this->attempts() > 3)
{
	//
}

注目： このメソッドを呼び出すには、Illuminate\Queue\InteractsWithQueueトレイトを使用する必要があります。Note: Your command / handler must use the Illuminate\Queue\InteractsWithQueue trait in order to call this method.

クロージャーのキューQueueing Closures

もしくはキューにクロージャーを登録することも可能です。これは手軽にシンプルなタスクをキュー登録する必要がある場合に大変便利です。You may also push a Closure onto the queue. This is very convenient for quick, simple tasks that need to be queued:

キューのクロージャー登録Pushing A Closure Onto The Queue

Queue::push(function($job) use ($id)
{
	Account::delete($id);

	$job->delete();
});

注目： useを使用し、キューするクロージャーでオブジェクトを使用できるように渡す代わりに主キーを渡し、キュージョブの中で関連するモデルを再取得する設計をしてください。これにより、シリアライズの予期しない影響を防ぐことができます。Note: Instead of making objects available to queued Closures via the use directive, consider passing primary keys and re-pulling the associated models from within your queue job. This often avoids unexpected serialization behavior.

Iron.ioのPushキューを利用する場合、キューのクロージャーで追加の予防策を取る必要があります。キューメッセージを受け取った時点でそのキューが本当にIron.ioからのリクエストであるかをチェックしてください。例えば、Pushキューの受け取りURLをhttps:://yourapp.com/queue/receive?token=秘密のトークンのような形式で登録します。次に、キューリクエストでmarshalメソッドを実行する前に、秘密のトークンの値をアプリケーションでチェックします。When using Iron.io push queues[#push-queues], you should take extra precaution queueing Closures. The end-point that receives your queue messages should check for a token to verify that the request is actually from Iron.io. For example, your push queue end-point should be something like: https://yourapp.com/queue/receive?token=SecretToken. You may then check the value of the secret token in your application before marshalling the queue request.

キューリスナーの実行Running The Queue Listener

LaravelのArtisanは、新しくキューに保存されたジョブを実行するコマンドを含んでいます。queue:listenコマンドで、このタスクを実行できます。Laravel includes an Artisan task that will run new jobs as they are pushed onto the queue. You may run this task using the queue:listen command:

キューリスナーの開始Starting The Queue Listener

php artisan queue:listen

リスナーに使用するキュー接続を指定することもできます。You may also specify which queue connection the listener should utilize:

php artisan queue:listen connection

このタスクを一度開始したら、手動で停止しない限り実行を続けることに注意してください。Supervisorのようなプロセスモニターを利用し、キューリスナーが確実に動作し続けるようにしてください。Note that once this task has started, it will continue to run until it is manually stopped. You may use a process monitor such as Supervisor[http://supervisord.org/] to ensure that the queue listener does not stop running.

listenコマンドにキューのプライオリティーを設定するため、キュー接続をカンマ区切りで指定することもできます。You may pass a comma-delimited list of queue connections to the listen command to set queue priorities:

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

この例で、high-connectionはlow-connectionのジョブを実行する前にいつも処理されます。In this example, jobs on the high-connection will always be processed before moving onto jobs from the low-connection.

ジョブのタイムアウト時間を指定するSpecifying The Job Timeout Parameter

それぞれのジョブの実行時間を秒数で指定することもできます。You may also set the length of time (in seconds) each job should be allowed to run:

php artisan queue:listen --timeout=60

キューのスリープ時間を指定するSpecifying Queue Sleep Duration

さらに、新しいジョブをポーリングする前に、待ち秒数を指定することもできます。In addition, you may specify the number of seconds to wait before polling for new jobs:

php artisan queue:listen --sleep=5

キューにジョブがない場合のみ、キューがスリープすることに注意して下さい。もし、ジョブが存在しているなら、キューはスリープせずに処理を続けます。Note that the queue only "sleeps" if no jobs are on the queue. If more jobs are available, the queue will continue to work them without sleeping.

キューの最初のジョブを実行するProcessing The First Job On The Queue

キューの最初のジョブだけを実行するには、queue:workコマンドを使用してください。To process only the first job on the queue, you may use the queue:work command:

php artisan queue:work

デーモンキューワーカーDaemon Queue Worker

queue:workはフレームワークを再起動せずに連続してジョブを処理し続けるように、キューワーカーを強制するための、--daemonオプションも備えています。これにより、queue:listenと比較すると、CPU使用率を大幅に引き下げることができますが、デプロイ中は現在実行中のジョブのキューを空にするために、複雑な手順の追加が必要になります。The queue:work also includes a --daemon option for forcing the queue worker to continue processing jobs without ever re-booting the framework. This results in a significant reduction of CPU usage when compared to the queue:listen command, but at the added complexity of needing to drain the queues of currently executing jobs during your deployments.

キュー・ワーカーをデーモンモードで開始するためには、--daemonフラッグを使用します。To start a queue worker in daemon mode, use the --daemon flag:

php artisan queue:work connection --daemon

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

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

ご覧の通り、queue:workコマンドはqueue:listenで使用できるものと、ほぼ同じオプションをサポートしています。php artisan help queue:workコマンドで全オプションを表示できます。As you can see, the queue:work command supports most of the same options available to queue:listen. You may use the php artisan help queue:work command to view all of the available options.

デーモンキューワーカーによるデプロイDeploying With Daemon Queue Workers

アプリケーションをデーモン・キュー・ワーカーでデプロイする、一番簡単な方法は、デプロイを開始するときに、アプリケーションをメンテナンスモードにすることです。php artisan downコマンドにより切り替えられます。アプリケーションをメンテナンスモードにすると、Laravelは新しいジョブをキューに受け付けなくなりますが、存在しているジョブの処理は続けます。The simplest way to deploy an application using daemon queue workers is to put the application in maintenance mode at the beginning of your deployment. This can be done using the php artisan down command. Once the application is in maintenance mode, Laravel will not accept any new jobs off of the queue, but will continue to process existing jobs.

ワーカーを一番簡単に再起動するには、デプロイスクリプトの中に、次のコマンドを含めてください。The easiest way to restart your workers is to include the following command in your deployment script:

php artisan queue:restart

このコマンドは、現在のジョブの処理が終了した後、全キューワーカーを再起動するように指示します。This command will instruct all queue workers to restart after they finish processing their current job.

注意： このコマンドは再起動のスケジュールするため、キャッシュシステムを利用しています。デフォルト状態では、APCuはCLIコマンドのために動作しません。APCuを使用する場合、apc.enable_cli=1をAPCu設定に追加してください。Note: This command relies on the cache system to schedule the restart. By default, APCu does not work for CLI commands. If you are using APCu, add apc.enable_cli=1 to your APCu configuration.

デーモンキューワーカーのコーディングCoding For Daemon Queue Workers

デーモンキューワーカーは、各ジョブを処理する前にフレームワークを再起動しません。そのため、多くのリソースを使用するジョブを完了する前に、それらを開放するように気をつけてください。例えば、GDライブラリーを使用し、画像処理を行う場合、完了したらimagedestroyでメモリを開放する必要があるでしょう。Daemon queue workers do not restart the framework before processing each job. Therefore, you should be careful to free any heavy resources before your job finishes. For example, if you are doing image manipulation with the GD library, you should free the memory with imagedestroy when you are done.

同様に、デーモンが長時間動作し、使用され続ければデータベース接続は切断されるでしょう。新しい接続を行うために、DB::reconnectメソッドを使う必要が起きるでしょう。Similarly, your database connection may disconnect when being used by long-running daemon. You may use the DB::reconnect method to ensure you have a fresh connection.

PushキューPush Queues

デーモンやバックグラウンドリスナーを走らせなくても、Pushキューを使えばLaravel5のキュー機能を存分に利用できます。現在、PushキューはIron.ioドライバーでしかサポートされていません。開始する前にIron.ioのアカウントを作成し、Ironの認証データーをconfig/queus.php設定ファイルに追加してください。Push queues allow you to utilize the powerful Laravel 5 queue facilities without running any daemons or background listeners. Currently, push queues are only supported by the Iron.io[http://iron.io] driver. Before getting started, create an Iron.io account, and add your Iron credentials to the config/queue.php configuration file.

Pushキュー購読の登録Registering A Push Queue Subscriber

次に、新しく登録されたキュージョブを受け取るエンドポイントURLをqueue::subscribe Artisanコマンドで登録します。Next, you may use the queue:subscribe Artisan command to register a URL end-point that will receive newly pushed queue jobs:

php artisan queue:subscribe queue_name queue/receive

php artisan queue:subscribe queue_name http://foo.com/queue/receive

これでIronダッシュボードへログインすると、新しいPushキューが購読URLと共に表示されます。指定したキューに対し、好きなだけURLを購読することもできます。次に、queue/receiveエンドポイントへのルートを生成し、Queue::marshalメソッドからのレスポンスをリターンしてください。Now, when you login to your Iron dashboard, you will see your new push queue, as well as the subscribed URL. You may subscribe as many URLs as you wish to a given queue. Next, create a route for your queue/receive end-point and return the response from the Queue::marshal method:

Route::post('queue/receive', function()
{
	return Queue::marshal();
});

marshalメソッドは正しいジョブハンドラークラスが実行されるように取り計らいます。Pushキューへのジョブを実行するには、Queue::pushメソッドと同様にキューの使用手順に従い利用してください。The marshal method will take care of firing the correct job handler class. To fire jobs onto the push queue, just use the same Queue::push method used for conventional queues.

失敗したジョブFailed Jobs

物事はうまく行かない場合もありますので、キュージョブが失敗することも想定できます。でも、心配ありません。最高な人たちも失敗はするものです！ Laravelは指定した回数ジョブを再実行する便利な方法を用意しています。この回数実行してもうまく行かない場合は、faild_jobsテーブルに登録されます。この失敗したジョブのテーブル名は、config/queue.php設定ファイルで指定できます。Since things don't always go as planned, sometimes your queued jobs will fail. Don't worry, it happens to the best of us! Laravel includes a convenient way to specify the maximum number of times a job should be attempted. After a job has exceeded this amount of attempts, it will be inserted into a failed_jobs table. The failed jobs table name can be configured via the config/queue.php configuration file.

faild_jobsテーブルのマイグレーションを生成するには、queue:faild-tableコマンドを実行して下さい。To create a migration for the failed_jobs table, you may use the queue:failed-table command:

php artisan queue:failed-table

ジョブ再実行の最大回数を指定するには、queue:listenコマンドに--triesスイッチを付け実行して下さい。You can specify the maximum number of times a job should be attempted using the --tries switch on the queue:listen command:

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

キュージョブが失敗した時に呼び出されるイベントのリスナーを登録したい場合は、Queue::failingメソッドを使って下さい。このイベントは、メールかHipChatであなたのチームに通知するために便利でしょう。If you would like to register an event that will be called when a queue job fails, you may use the Queue::failing method. This event is a great opportunity to notify your team via e-mail or HipChat[https://www.hipchat.com].

Queue::failing(function($connection, $job, $data)
{
	//
});

キュージョブクラスへ直接failedメソッドを定義すると、失敗が起きたときに指定されたアクションが実行されるようになります。You may also define a failed method directly on a queue job class, allowing you to perform job specific actions when a failure occurs:

public function failed()
{
	// ジョブが失敗した時に呼ばれる…
}

失敗したジョブの再実行Retrying Failed Jobs

失敗したジョブを全部確認するには、queue:failed Arisanコマンドを利用します。To view all of your failed jobs, you may use the queue:failed Artisan command:

php artisan queue:failed

queue:failedコマンドにジョブIDを指定すれば、接続、キュー、失敗した時間がリストされます。ジョブIDは失敗したジョブを再実行する場合にも使用します。例えば、IDが5の失敗したジョブを再実行するには、以下のコマンドを実行します。The queue:failed command will list the job ID, connection, queue, and failure time. The job ID may be used to retry the failed job. For instance, to retry a failed job that has an ID of 5, the following command should be issued:

php artisan queue:retry 5

失敗したジョブを削除するには、queue:forgetコマンドを使います。If you would like to delete a failed job, you may use the queue:forget command:

php artisan queue:forget 5

失敗したジョブを全部消去するには、queue:flushコマンドを使用します。To delete all of your failed jobs, you may use the queue:flush command:

php artisan queue:flush