事件與監聽器

事件是什麼

Laravel 的事件系統是簡潔的觀察者模式實作。你可以透過在應用程式中發生「事件」時觸發，並定義能對其做出反應的監聽器，將元件之間的相依性降到最低。例如，發起「訂單成立」事件後，「發送確認信」、「扣減庫存」、「通知 Slack」等多個監聽器都能各自獨立地執行。訂單處理程式碼完全不需要知道 email 或 Slack 通知的實作細節。

事件類別存放於 app/Events，監聽器類別存放於 app/Listeners。若不存在則 Artisan 指令會自動建立。

建立事件與監聽器

以 make:event 與 make:listener Artisan 指令產生類別骨架。

php artisan make:event UserRegistered

php artisan make:listener SendWelcomeEmail --event=UserRegistered

不帶參數執行時會進入互動模式。

php artisan make:event

php artisan make:listener

註冊事件

事件自動探索

預設情況下，Laravel 會掃描 app/Listeners 目錄自動註冊監聽器。它會依 handle 或 __invoke 方法的引數型別推論與事件的對應。

use App\Events\UserRegistered;

class SendWelcomeEmail
{
    public function handle(UserRegistered $event): void
    {
        // 寄送歡迎信
    }
}

透過 PHP 的聯合型別，可讓單一方法接收多種事件。

public function handle(UserRegistered|UserUpdated $event): void
{
    // ...
}

若把監聽器放在其他目錄，可於 bootstrap/app.php 指定額外掃描位置。

->withEvents(discover: [
    __DIR__.'/../app/Domain/Orders/Listeners',
])

也可用 wildcard 指定多個目錄。

->withEvents(discover: [
    __DIR__.'/../app/Domain/*/Listeners',
])

要確認已註冊的監聽器可執行下列指令。

php artisan event:list

在正式環境快取監聽器 manifest 可提升效能。部署時可執行 php artisan optimize 或 php artisan event:cache。要清除快取則使用 php artisan event:clear。

手動註冊

也可以在 AppServiceProvider 的 boot 方法透過 Event Facade 手動註冊。

use App\Events\UserRegistered;
use App\Listeners\SendWelcomeEmail;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(
        UserRegistered::class,
        SendWelcomeEmail::class,
    );
}

也可以透過閉包註冊。

use App\Events\UserRegistered;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(function (UserRegistered $event) {
        // ...
    });
}

定義事件

事件類別是資料的容器。它不含邏輯，只以屬性儲存與事件相關的資訊。

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public User $user,
    ) {}
}

透過 SerializesModels trait，可在佇列化的監聽器序列化事件時正確處理 Eloquent 模型。

觸發事件

透過 dispatch 靜態方法或 event() 輔助函式觸發事件。

use App\Events\UserRegistered;

// 靜態方法
UserRegistered::dispatch($user);

// 輔助函式
event(new UserRegistered($user));

也有依條件觸發的方法。

UserRegistered::dispatchIf($condition, $user);

UserRegistered::dispatchUnless($condition, $user);

資料庫 Transaction 之後才觸發

若要在 transaction commit 之後才觸發事件，可在事件類別實作 ShouldDispatchAfterCommit 介面。若 transaction 失敗則事件會被丟棄。

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered implements ShouldDispatchAfterCommit
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public User $user,
    ) {}
}

監聽器的實作

監聽器透過 handle 方法接收事件。建構子中的相依會由服務容器自動注入。

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail
{
    public function __construct() {}

    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user->email)
            ->send(new WelcomeMail($event->user));
    }
}

若監聽器的 handle 方法回傳 false，可以中斷事件傳遞到後續監聽器。

佇列化的監聽器

寄信或 HTTP 請求等耗時處理，可作為佇列化的監聽器非同步執行。只需實作 ShouldQueue 介面，事件觸發時監聽器就會自動進入佇列。

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        // 此處理由佇列 worker 非同步執行
    }
}

使用佇列化的監聽器前，需先設定佇列並啟動 worker。詳情請見佇列與工作頁面。

自訂佇列連線 / 名稱 / 延遲

可用 PHP 屬性設定連線、佇列名稱與延遲時間。

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Delay;
use Illuminate\Queue\Attributes\Queue;

#[Connection('redis')]
#[Queue('emails')]
#[Delay(10)]
class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        // ...
    }
}

也可以用方法動態決定值。

public function viaConnection(): string
{
    return 'redis';
}

public function viaQueue(): string
{
    return 'emails';
}

public function withDelay(UserRegistered $event): int
{
    return 10;
}

最大重試次數與逾時

使用 #[Tries] 與 #[Timeout] 屬性控制失敗時的行為。

use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;

#[Tries(3)]
#[Timeout(30)]
class SendWelcomeEmail implements ShouldQueue
{
    // ...
}

失敗時的處理

定義 failed 方法可以描述監聽器超過重試次數後失敗的後續處理。

use Throwable;

public function failed(UserRegistered $event, Throwable $exception): void
{
    // 通知管理員等
}

事件訂閱者

透過事件訂閱者，可以將多個相關事件處理程式集中在同一個類別。

建立訂閱者

在 subscribe 方法回傳事件與 handler 的對應陣列。

<?php

namespace App\Listeners;

use Illuminate\Auth\Events\Login;
use Illuminate\Auth\Events\Logout;
use Illuminate\Events\Dispatcher;

class UserActivitySubscriber
{
    public function handleLogin(Login $event): void
    {
        // 登入處理
    }

    public function handleLogout(Logout $event): void
    {
        // 登出處理
    }

    /**
     * @return array<string, string>
     */
    public function subscribe(Dispatcher $events): array
    {
        return [
            Login::class => 'handleLogin',
            Logout::class => 'handleLogout',
        ];
    }
}

註冊訂閱者

若事件自動探索啟用，subscribe 方法回傳陣列的訂閱者會自動註冊。若要手動註冊，可在 AppServiceProvider 的 boot 方法呼叫 Event::subscribe。

use App\Listeners\UserActivitySubscriber;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::subscribe(UserActivitySubscriber::class);
}

實戰範例：使用者註冊時寄送歡迎信

建立事件類別

php artisan make:event UserRegistered

編輯 app/Events/UserRegistered.php，加入用來保存註冊使用者的屬性。

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public User $user,
    ) {}
}

建立監聽器類別

php artisan make:listener SendWelcomeEmail --event=UserRegistered

為了讓寄信非同步進行，實作 ShouldQueue。

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user->email)
            ->send(new WelcomeMail($event->user));
    }
}

在控制器中觸發事件

在使用者註冊處理後呼叫 UserRegistered::dispatch()。

<?php

namespace App\Http\Controllers\Auth;

use App\Events\UserRegistered;
use App\Models\User;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class RegisterController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $user = User::create($request->validated());

        UserRegistered::dispatch($user);

        return redirect('/dashboard');
    }
}

RegisterController 只需要觸發 UserRegistered 事件，不需要知道寄信的實作。未來如果加入「註冊時也通知 Slack」的需求，也完全不必修改控制器。

啟動 worker

要處理佇列化的監聽器，請啟動 worker。

php artisan queue:work

在事件自動探索啟用時，不需要在 AppServiceProvider 手動註冊。放在 app/Listeners 目錄的監聽器會被自動偵測。

執行 php artisan event:list 可以查看已註冊的事件與監聽器清單。請定期檢查是否有意料外的監聽器。

架構

資料庫

Eloquent

安全性

事件

郵件與通知

付款

非同步處理

即時通訊

排程

快取與最佳化

國際化

檔案與儲存

偵錯與監控

主控台與 CLI

效能

前端

AI 開發

開發環境

事件是什麼

建立事件與監聽器

註冊事件

事件自動探索

手動註冊

定義事件

觸發事件

資料庫 Transaction 之後才觸發

監聽器的實作

佇列化的監聽器

自訂佇列連線 / 名稱 / 延遲

最大重試次數與逾時

失敗時的處理

事件訂閱者

建立訂閱者

註冊訂閱者

實戰範例：使用者註冊時寄送歡迎信

​事件是什麼

​建立事件與監聽器

​註冊事件

​事件自動探索

​手動註冊

​定義事件

​觸發事件

​資料庫 Transaction 之後才觸發

​監聽器的實作

​佇列化的監聽器

​自訂佇列連線 / 名稱 / 延遲

​最大重試次數與逾時

​失敗時的處理

​事件訂閱者

​建立訂閱者

​註冊訂閱者

​實戰範例：使用者註冊時寄送歡迎信

事件是什麼

建立事件與監聽器

註冊事件

事件自動探索

手動註冊

定義事件

觸發事件

資料庫 Transaction 之後才觸發

監聽器的實作

佇列化的監聽器

自訂佇列連線 / 名稱 / 延遲

最大重試次數與逾時

失敗時的處理

事件訂閱者

建立訂閱者

註冊訂閱者

實戰範例：使用者註冊時寄送歡迎信