隊列
簡介
Laravel 的隊列服務為不同的隊列後端系統提供一個統一的 API 。隊列允許你將一個耗時的任務延遲處理，例如像寄送 e-mail，這會使得你的應用程式對網頁請求有更快的反應。
設定
隊列的設定檔被儲存在 config/queue.php。在這個檔案裡你可以找到包含在 Laravel 框架中，每一種隊列驅動的連結設定。它們包含了資料庫、Beanstalkd、IronMQ、Amazon SQS、Redis 以及提供本機使用的 synchronous 驅動。
另外框架也提供了 null 這個隊列驅動，用來丟棄隊列任務。
驅動必要設定
資料庫
要使用 database 這個隊列驅動的話，需要建立一個資料表來記住任務，你可以用 queue:table 這個 Artisan 指令來建立這個資料表的遷移類別。當遷移類別建好後，就可以用 migrate 這個指令來將資料表在資料庫中建立起來。
php artisan queue:table
php artisan migrate其他隊列系統的相依套件
要使用列表裡的隊列服務前，必須安裝以下的相依套件：
- Amazon SQS：
aws/aws-sdk-php ~3.0 - Beanstalkd：
pda/pheanstalk ~3.0 - IronMQ：
iron-io/iron_mq ~2.0|~4.0 - Redis：
predis/predis ~1.0
撰寫任務類別
產生任務類別
在你的應用程式中，所有能放在隊列的任務類別預設放在 app/Jobs 目錄下，你可以用以下的 Artisan 指令來產生一個新的隊列任務：
php artisan make:job SendReminderEmail --queued這個指令將會在 app/Jobs 下產生一個新類別，而這個類別會實作 Illuminate\Contracts\Queue\ShouldQueue 介面，讓 Laravel 知道這個任務應該是被放到隊列裡，而不是直接執行。
任務類別結構
任務類別的結構很簡單，一般來說只會包含一個讓隊列用來呼叫此任務的 handle 方法。我們用以下這個類別來做示範：
<?php
namespace 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\Bus\SelfHandling;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendReminderEmail extends Job implements SelfHandling, 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 模型。因為我們在任務類別裡引用了 SerializesModels 這個 trait，使得 Eloquent 模型在處理任務的時候可以被優雅地序列化和反序列化。如果你的隊列任務類別在建構子接受一個 Eloquent 模型，那麼只有可識別出該模型的屬性會被序列化至隊列裡。當任務實際被執行時，隊列系統會自動從資料庫中重新取回完整的模型。整個過程對你的應用程式來說是透明的，這樣可以避免序列化完整的 Eloquent 的模式實例所帶來的問題。
在隊列處理任務時，會呼叫 handle 方法，而這裡我們也可以透過 handle 方法的參數型別提示，讓 Laravel 的服務容器自動注入相依物件。
當發生錯誤的時候
如果在任務處理時拋出了一個例外，它會自動被釋放回隊列裡再次嘗試執行。當該任務一直出錯時，它會不斷被釋出再重試，直到超過你的應用程式所允許的最大重試值。最大重試值可以在執行 queue:listen 或 queue:work 指令時，用 --tries 選項來設定；執行隊列監聽器的更多資訊在稍後會有詳細說明。
手動釋放任務
如果你想手動釋放任務，那麼在產生出來的任務類別已經引用了 InteractsWithQueue 這個 trait，它提供了 release 方法讓我們可以釋放任務。在 release 方法中接受一個數值參數，它表示直到這個任務可以被重新執行之前，你願意等待的秒數。
public function handle(Mailer $mailer)
{
if (condition) {
$this->release(10);
}
}檢查重試次數
如同前面提到的，當任務被處理時發生了一個例外，它會自動被釋放回隊列中。這時候你可以用 attempt 方法來檢查已經重試的次數：
public function handle(Mailer $mailer)
{
if ($this->attempts() > 3) {
//
}
}將任務推送到隊列上
在 app/Http/Controllers/Controller.php 中 Laravel 定義了一個預設控制器，它引用了 DispatchesJob 這個 trait；而這個 trait 提供了數個可以讓你方便推送任務到隊列的方法，例如 dispatch 方法：
<?php
namespace App\Http\Controllers;
use App\User;
use Illuminate\Http\Request;
use App\Jobs\SendReminderEmail;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* 寄送提醒的 e-mail 給指定使用者。
*
* @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 ，以便使用它的各種派發方法。以下就是使用該 trait 的類別範例：
<?php
namespace App;
use Illuminate\Foundation\Bus\DispatchesJobs;
class ExampleClass
{
use DispatchesJobs;
}指定任務所屬的隊列
你可以指定任務應該要送到哪一個隊列。
要推送任務到不同的隊列上，你要將任務先「分類」，甚至可能要排定每個隊列能有多少作業器可以執行任務。這並不是指任務會推送到你在設定檔所定義的不同隊列連結裡，而是推送到某個有單一連結的隊列。要指定任務執行的隊列，可以用任務實例的 onQueue 方法。onQueue 是 Illuminate\Bus\Queueable trait 所提供的方法，而它已經包含在 App\Jobs\Job 基底類別中：
<?php
namespace App\Http\Controllers;
use App\User;
use Illuminate\Http\Request;
use App\Jobs\SendReminderEmail;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* 寄送提醒的 e-mail 給指定使用者。
*
* @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);
}
}延遲性任務
有時你可能會希望隊列任務能晚一點再執行，例如在使用者註冊後 15 分鐘後才透過隊列任務寄送提醒信件。你可以透過任務類別引用的 Illuminate\Bus\Queueable 這個 trait 所提供的 delay 方法來達成這個目的：
<?php
namespace App\Http\Controllers;
use App\User;
use Illuminate\Http\Request;
use App\Jobs\SendReminderEmail;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* 寄送提醒的 e-mail 給指定使用者。
*
* @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 分鐘。
從請求中派送任務
在任務中對應到 HTTP 請求的變數是很常見的，所以與其強制你手動去對每個請求做這件事，Laravel 直接提供了一些輔助方法讓你更容易做到它；像是在 DispatchesJobs 這個 trait 就提供了 dispatchFrom 方法，而 Laravel 基礎控制器就預設引入了這個 trait：
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class CommerceController extends Controller
{
/**
* 處理指定的訂單。
*
* @param Request $request
* @param int $id
* @return Response
*/
public function processOrder(Request $request, $id)
{
// 處理該請求...
$this->dispatchFrom('App\Jobs\ProcessOrder', $request);
}
}這個方法會檢查任務類別的建構子，並且從 HTTP 請求 (或任何 ArrayAccess 物件) 中取出變數，來填補建構子中需要的參數。所以如果我們的任務類別建構子接受一個 productId 變數的話，那麼隊列就會試著從 HTTP 請求中提出 productId 這個參數。
你也可以直接將一個陣列傳入到 dispatchFrom 方法的第三個參數裡，這個陣列就會被用來填補建構子中任何不在請求裡的變數：
$this->dispatchFrom('App\Jobs\ProcessOrder', $request, [
'taxPercentage' => 20,
]);任務事件
任務完成事件
Queue::after 方法讓你能夠註冊一個回呼，當隊列任務執行完成後就會被執行。在此回呼進行額外的紀錄、隊列後續任務、或為儀表板增加統計都是很好的時機。舉個例子，我們可以在 Laravel 所包含的 AppServiceProvider 附加一個回呼到此事件：
<?php
namespace App\Providers;
use Queue;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* 啟動所有應用程式服務。
*
* @return void
*/
public function boot()
{
Queue::after(function ($connection, $job, $data) {
//
});
}
/**
* 註冊服務提供者。
*
* @return void
*/
public function register()
{
//
}
}執行隊列監聽器
啟動隊列監聽器
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注意這裡是指隊列在沒有任務的狀態下才會休眠；如果已經有多個任務卡在這個隊列上，那麼它會持續運作而不會休眠。
Supervisor 設定
Supervisor 是一個在 Linux 作業系統上的行程監控軟體，它會在 queue:listen 或 queue:work 指令發生失敗後自動重啟它們。要在 Ubuntu 安裝 Supervisor，可以用以下指令：
sudo apt-get install supervisorSupervisor 的設定檔一般是放在 /etc/supervisor/conf.d 目錄下，在這個目錄中你可以建立任意數量的設定檔，要求 Supervisor 來監控你的行程。例如我們建立一個 laravel-worker.conf 來啟動與監控一個 queue:work 行程：
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/forge/app.com/artisan queue:work sqs --sleep=3 --tries=3 --daemon
autostart=true
autorestart=true
user=forge
numprocs=8
redirect_stderr=true
stdout_logfile=/home/forge/app.com/worker.log在這個範例裡的 numprocs 指令會要求 Supervisor 執行並監控 8 個 queue:work 行程，並且在它們執行失敗時重新啟動。當然，你必須更改 command 指令的 queue:work sqs 部分，以顯示你所選擇的隊列驅動。
當這個設定檔建立後，你需要更新 Supervisor 的設定，並用以下指令來啟動該行程：
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*更多有關 Supervisor 的設定與使用，請參考 Supervisor 官方文件。或是你可以使用 Laravel Forge 所提供的 Web 介面，來自動設定與管理你的 Supervisor 設定。
將任務監聽器設為背景服務
在 queue:work Artisan 指令裡包含了 --daemon 選項，強迫隊列作業器持續處理任務，而不需要重新啟動整個框架。比起 queue:listen 指令，這會顯著減少 CPU 的用量。
用 --daemon 旗標在背景服務模式下啟動隊列作業器：
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 指令來查看所有可用的選項。
在背景服務的隊列監聽器中開發所要考量的事項
在背景執行的隊列監聽器在處理完每個任務前，不會重新啟動框架；因此你應該在任務執行完成前，謹慎地釋放任何佔用記憶體較重的資源。例如你利用 GD 函式庫處理影像，就要在結束前用 imagedestroy 來釋放記憶體。
相同地，你的資料庫連結也要在使用完後關閉連線；你可以用 DB::reconnect 方法來確保有新的資料庫連線。
隨著在背景服務的任務監聽器進行佈署
從背景服務的隊列作業器是長時間執行的行程來看，除非重新啟動，否則它們將不會理會任何程式碼上的變更。所以要佈署一個有用到背景服務的隊列作業器的應用程式，最簡單的方法就是在佈署指令稿中重新啟動作業器。你可以在你的佈署指令裡加上以下指令，來優雅地重新啟動所有作業器：
php artisan queue:restart這個指令會優雅地告知所有隊列作業器，在它們完成處理目前任務後重新啟動，所以就不會任務遺失的問題。
注意：這個指令依靠快取系統來安排重新啟動；預設狀況下，APCu 無法在 CLI 的任務上運作；如果你正在使用 APCu 的話，要把
apc.enable_cli=1加到你的 APCu 設定裡。
處理失敗的任務
計劃永遠跟不上變化，有時候你的隊列任務就是會失敗。不過別擔心，我們有準備好它發生時的應付方法。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任務失敗事件
如果你想註冊一個當隊列任務失敗時會被呼叫的事件，你可以用 Queue::failing 方法；這樣你就有機會透過這個事件，用 e-mail 或 HipChat 來通知你的團隊。例如我們可以在 Laravel 內建的 AppServiceProvider 中對這個事件附加一個回呼函式：
<?php
namespace App\Providers;
use Queue;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* 啟動任何應用程式的服務。
*
* @return void
*/
public function boot()
{
Queue::failing(function ($connection, $job, $data) {
// 通知團隊失敗的任務...
});
}
/**
* 註冊服務容器。
*
* @return void
*/
public function register()
{
//
}
}任務類別裡處理失敗的方法
如果想有更細膩的控制，你可以在直接在任務類別裡定義一個 failed 方法，這個方法允許你指定在錯誤發生時該怎麼動作。
<?php
namespace 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()
{
// 當任務失敗時會被呼叫...
}
}重新嘗試執行失敗任務
要檢視你在 failed_jobs 資料表中所有失敗的任務，你可以用 queue:failed 這個 Artisan 指令：
php artisan queue:failedqueue:failed 指令會列出所有任務 ID、連結、隊列以及失敗時間，任務 ID 會用在重試失敗的任務。例如要重試一個 ID 為 5 的失敗任務，其指令如下：
php artisan queue:retry 5要重試所有失敗的任務，可以使用 queue:retry 並使用 all 作為 ID：
php artisan queue:retry all如果你想刪除掉一個失敗任務，可以用 queue:forget 指令：
php artisan queue:forget 5queue:flush 指令可以讓你刪除所有失敗的任務：
php artisan queue:flush