Laravel 11.x イベント

イントロダクションIntroduction

Laravelのイベントは、単純なオブザーバーパターンの実装を提供し、アプリケーション内で発生するさまざまなイベントをサブスクライブしてリッスンできるようにします。イベントクラスは通常、app/Eventsディレクトリに保存し、リスナはapp/Listenersに保存します。Artisanコンソールコマンドを使用してイベントとリスナを生成すると、これらのディレクトリが作成されるため、アプリケーションにこれらのディレクトリが表示されていなくても心配ありません。Laravel's events provide a simple observer pattern implementation, allowing you to subscribe and listen for various events that occur within your application. Event classes are typically stored in the app/Events directory, while their listeners are stored in app/Listeners. Don't worry if you don't see these directories in your application as they will be created for you as you generate events and listeners using Artisan console commands.

１つのイベントに、相互に依存しない複数のリスナを含めることができるため、イベントは、アプリケーションのさまざまな側面を分離するための優れた方法として機能します。たとえば、注文が発送されるたびにユーザーにSlack通知を送信したい場合があります。注文処理コードをSlack通知コードに結合する代わりに、リスナが受信してSlack通知をディスパッチするために使用できるApp\Events\OrderShippedイベントを発生させることができます。Events serve as a great way to decouple various aspects of your application, since a single event can have multiple listeners that do not depend on each other. For example, you may wish to send a Slack notification to your user each time an order has shipped. Instead of coupling your order processing code to your Slack notification code, you can raise an App\Events\OrderShipped event which a listener can receive and use to dispatch a Slack notification.

イベントとリスナの生成Generating Events and Listeners

イベントとリスナを素早く生成するには、make:eventとmake:listenerのArtisanコマンドを使います。To quickly generate events and listeners, you may use the make:event and make:listener Artisan commands:

php artisan make:event PodcastProcessed

php artisan make:listener SendPodcastNotification --event=PodcastProcessed

使いやすいように、引数を指定せずにmake:eventとmake:listener Artisanコマンドを呼び出すこともできます。その場合、Laravelは自動的にクラス名、リスナを作成する場合はクラス名と、そのリスナがリッスンするイベントのクラス名を求めるプロンプトを表示します。For convenience, you may also invoke the make:event and make:listener Artisan commands without additional arguments. When you do so, Laravel will automatically prompt you for the class name and, when creating a listener, the event it should listen to:

php artisan make:event

php artisan make:listener

イベントとリスナの登録Registering Events and Listeners

イベント追跡Event Discovery

Laravelはデフォルトで、アプリケーションのListenersディレクトリをスキャンして、イベントリスナを自動的に見つけて登録します。handleまたは__invokeで始まるリスナクラスのメソッドが見つかると、Laravelはそれらのメソッドを、メソッドのシグネチャでタイプヒントしてあるイベントのイベントリスナとして登録します。By default, Laravel will automatically find and register your event listeners by scanning your application's Listeners directory. When Laravel finds any listener class method that begins with handle or __invoke, Laravel will register those methods as event listeners for the event that is type-hinted in the method's signature:

use App\Events\PodcastProcessed;

class SendPodcastNotification
{
    /**
     * 指定イベントの処理
     */
    public function handle(PodcastProcessed $event): void
    {
        // ...
    }
}

PHPのユニオン型を使い、複数のイベントをリッスンできます。You may listen to multiple events using PHP's union types:

/**
 * 指定イベントの処理
 */
public function handle(PodcastProcessed|PodcastPublished $event): void
{
    // ...
}

リスナを別のディレクトリや複数のディレクトリへ保存する場合は、アプリケーションのbootstrap/app.phpファイルでwithEventsメソッドを使用し、それらのディレクトリをスキャンするようにLaravelに指示してください。If you plan to store your listeners in a different directory or within multiple directories, you may instruct Laravel to scan those directories using the withEvents method in your application's bootstrap/app.php file:

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

event:listコマンドは、アプリケーションに登録したすべてのリスナをリストアップするために使用します。The event:list command may be used to list all of the listeners registered within your application:

php artisan event:list

実機でのイベント追跡Event Discovery in Production

アプリケーションを高速化するために、optimizeまたはevent:cache Artisanコマンドを使用して、アプリケーションのすべてのリスナのマニフェストをキャッシュする必要があります。通常、このコマンドはアプリケーションのデプロイプロセスの一部として実行する必要があります。このマニフェストは、イベント登録処理を高速化するためにフレームワークが使用します。イベントキャッシュを破棄するには、event:clearコマンドを使用します。To give your application a speed boost, you should cache a manifest of all of your application's listeners using the optimize or event:cache Artisan commands. Typically, this command should be run as part of your application's deployment process[/docs/{{version}}/deployment#optimization]. This manifest will be used by the framework to speed up the event registration process. The event:clear command may be used to destroy the event cache.

イベントの手作業登録Manually Registering Events

Eventファサードを使用すると、アプリケーションのAppServiceProviderのbootメソッド内で、イベントとそれに対応するリスナを手作業で登録できます。Using the Event facade, you may manually register events and their corresponding listeners within the boot method of your application's AppServiceProvider:

use App\Domain\Orders\Events\PodcastProcessed;
use App\Domain\Orders\Listeners\SendPodcastNotification;
use Illuminate\Support\Facades\Event;

/**
 * アプリケーションの全サービスの初期起動処理
 */
public function boot(): void
{
    Event::listen(
        PodcastProcessed::class,
        SendPodcastNotification::class,
    );
}

event:listコマンドは、アプリケーションに登録しているすべてのリスナをリストアップするために使用します。The event:list command may be used to list all of the listeners registered within your application:

php artisan event:list

クロージャリスナClosure Listeners

通常、リスナはクラスとして定義しますが、アプリケーションのAppServiceProviderのbootメソッドで、手作業でクロージャベースのイベントリスナを登録することもできます。Typically, listeners are defined as classes; however, you may also manually register closure-based event listeners in the boot method of your application's AppServiceProvider:

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

/**
 * アプリケーションの全サービスの初期起動処理
 */
public function boot(): void
{
    Event::listen(function (PodcastProcessed $event) {
        // ...
    });
}

Queueable匿名イベントリスナQueueable Anonymous Event Listeners

クロージャベースのイベントリスナを登録するとき、リスナのクロージャをIlluminate\Events\queueable関数でラップして、キューを使用してリスナを実行するように、Laravelへ指示できます。When registering closure based event listeners, you may wrap the listener closure within the Illuminate\Events\queueable function to instruct Laravel to execute the listener using the queue[/docs/{{version}}/queues]:

use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;

/**
 * アプリケーションの全サービスの初期起動処理
 */
public function boot(): void
{
    Event::listen(queueable(function (PodcastProcessed $event) {
        // ...
    }));
}

キュー投入ジョブと同様に、onConnection、onQueue、delayメソッドを使用して、キュー投入するリスナの実行をカスタマイズできます。Like queued jobs, you may use the onConnection, onQueue, and delay methods to customize the execution of the queued listener:

Event::listen(queueable(function (PodcastProcessed $event) {
    // ...
})->onConnection('redis')->onQueue('podcasts')->delay(now()->addSeconds(10)));

キューに投入した匿名リスナの失敗を処理したい場合は、queueableリスナを定義するときにcatchメソッドにクロージャを指定できます。このクロージャは、リスナの失敗の原因となったイベントインスタンスとThrowableインスタンスを受け取ります。If you would like to handle anonymous queued listener failures, you may provide a closure to the catch method while defining the queueable listener. This closure will receive the event instance and the Throwable instance that caused the listener's failure:

use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;
use Throwable;

Event::listen(queueable(function (PodcastProcessed $event) {
    // ...
})->catch(function (PodcastProcessed $event, Throwable $e) {
    // キュー投入したリスナは失敗した…
}));

ワイルドカードイベントリスナWildcard Event Listeners

ワイルドカードパラメータとして、*文字を使用してリスナを登録することもでき、同じリスナで複数のイベントをキャッチできます。ワイルドカードリスナは、最初の引数にイベント名を受け取り、２番目の引数にイベントデータ配列全体を受け取ります。You may also register listeners using the * character as a wildcard parameter, allowing you to catch multiple events on the same listener. Wildcard listeners receive the event name as their first argument and the entire event data array as their second argument:

Event::listen('event.*', function (string $eventName, array $data) {
    // ...
});

イベント定義Defining Events

イベントクラスは、基本的に、イベントに関連する情報を保持するデータコンテナです。たとえば、App\Events\OrderShippedイベントがEloquent ORMオブジェクトを受け取るとします。An event class is essentially a data container which holds the information related to the event. For example, let's assume an App\Events\OrderShipped event receives an Eloquent ORM[/docs/{{version}}/eloquent] object:

<?php

namespace App\Events;

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

class OrderShipped
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * 新しいイベントインスタンスの生成
     */
    public function __construct(
        public Order $order,
    ) {}
}

ご覧のとおり、このイベントクラスにはロジックが含まれていません。購読したApp\Models\Orderインスタンスのコンテナです。イベントで使用されるSerializesModelsトレイトは、キュー投入するリスナを利用する場合など、イベントオブジェクトがPHPのserialize関数を使用してシリアル化される場合、Eloquentモデルを適切にシリアル化します。As you can see, this event class contains no logic. It is a container for the App\Models\Order instance that was purchased. The SerializesModels trait used by the event will gracefully serialize any Eloquent models if the event object is serialized using PHP's serialize function, such as when utilizing queued listeners[#queued-event-listeners].

リスナ定義Defining Listeners

次に、例題のイベントのリスナを見てみましょう。イベントリスナはhandleメソッドで、イベントインスタンスを受け取ります。make:listener Artisanコマンドは、--eventオプションを指定して呼び出すと、自動的に適切なイベントクラスをインポートし、handleメソッド内でイベントをタイプヒントします。handleメソッド内では、イベントに応答するために必要なアクションを実行できます。Next, let's take a look at the listener for our example event. Event listeners receive event instances in their handle method. The make:listener Artisan command, when invoked with the --event option, will automatically import the proper event class and type-hint the event in the handle method. Within the handle method, you may perform any actions necessary to respond to the event:

<?php

namespace App\Listeners;

use App\Events\OrderShipped;

class SendShipmentNotification
{
    /**
     * イベントリスナの生成
     */
    public function __construct() {}

    /**
     * イベントの処理
     */
    public function handle(OrderShipped $event): void
    {
        // $event->orderを使用して注文にアクセス
    }
}

lightbulb Note: イベントリスナは、コンストラクタに必要な依存関係をタイプヒントすることもできます。すべてのイベントリスナはLaravelサービスコンテナを介して依存解決されるため、依存関係は自動的に注入されます。[!NOTE]
Your event listeners may also type-hint any dependencies they need on their constructors. All event listeners are resolved via the Laravel service container[/docs/{{version}}/container], so dependencies will be injected automatically.

イベント伝播の停止Stopping The Propagation Of An Event

場合によっては、他のリスナへのイベント伝播を停止したいことがあります。これを行うには、リスナのhandleメソッドからfalseを返します。Sometimes, you may wish to stop the propagation of an event to other listeners. You may do so by returning false from your listener's handle method.

キュー投入するイベントリスナQueued Event Listeners

リスナをキューに投入することは、リスナが電子メールの送信やHTTPリクエストの作成などの遅いタスクを実行する場合に役立ちます。キューに入れられたリスナを使用する前に、必ずキューを設定して、サーバまたはローカル開発環境でキューワーカを起動してください。Queueing listeners can be beneficial if your listener is going to perform a slow task such as sending an email or making an HTTP request. Before using queued listeners, make sure to configure your queue[/docs/{{version}}/queues] and start a queue worker on your server or local development environment.

リスナをキュー投入するように指定するには、リスナクラスへShouldQueueインターフェイスを追加します。make:listener Artisanコマンドが生成したリスナは、あらかじめこのインターフェイスを現在の名前空間へインポートしているので、すぐに使用できます。To specify that a listener should be queued, add the ShouldQueue interface to the listener class. Listeners generated by the make:listener Artisan commands already have this interface imported into the current namespace so you can use it immediately:

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    // ...
}

これだけです！これで、このリスナによって処理されるイベントがディスパッチされると、リスナはLaravelのキューシステムを使用してイベントディスパッチャによって自動的にキューへ投入されます。リスナがキューによって実行されたときに例外が投げられない場合、キュー投入済みジョブは、処理が終了した後で自動的に削除されます。That's it! Now, when an event handled by this listener is dispatched, the listener will automatically be queued by the event dispatcher using Laravel's queue system[/docs/{{version}}/queues]. If no exceptions are thrown when the listener is executed by the queue, the queued job will automatically be deleted after it has finished processing.

キュー接続と名前、遅延のカスタマイズCustomizing The Queue Connection, Name, & Delay

イベントリスナのキュー接続、キュー名、またはキュー遅延時間をカスタマイズする場合は、リスナクラスで$connection、$queue、$delayプロパティを定義できます。If you would like to customize the queue connection, queue name, or queue delay time of an event listener, you may define the $connection, $queue, or $delay properties on your listener class:

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    /**
     * ジョブの送信先となる接続名
     *
     * @var string|null
     */
    public $connection = 'sqs';

    /**
     * ジョブの送信先となるキュー名
     *
     * @var string|null
     */
    public $queue = 'listeners';

    /**
     * ジョブを処理するまでの時間(秒)
     *
     * @var int
     */
    public $delay = 60;
}

実行時にリスナのキュー接続、キュー名、遅延時間を定義したい場合は、リスナにviaConnection、viaQueue、withDelayメソッドを定義します。If you would like to define the listener's queue connection, queue name, or delay at runtime, you may define viaConnection, viaQueue, or withDelay methods on the listener:

/**
 * リスナのキュー接続の名前の取得
 */
public function viaConnection(): string
{
    return 'sqs';
}

/**
 * リスナのキュー名を取得
 */
public function viaQueue(): string
{
    return 'listeners';
}

/**
 * ジョブを開始するまでの秒数を取得
 */
public function withDelay(OrderShipped $event): int
{
    return $event->highPriority ? 0 : 60;
}

条件付き投入リスナConditionally Queueing Listeners

場合によっては、実行時にのみ使用可能なデータに基づいて、リスナをキュー投入する必要があるかどうかを判断する必要が起きるでしょう。このために、shouldQueueメソッドをリスナに追加して、リスナをキュー投入する必要があるかどうかを判断できます。shouldQueueメソッドがfalseを返す場合、リスナはキュー投入されません。Sometimes, you may need to determine whether a listener should be queued based on some data that are only available at runtime. To accomplish this, a shouldQueue method may be added to a listener to determine whether the listener should be queued. If the shouldQueue method returns false, the listener will not be queued:

<?php

namespace App\Listeners;

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

class RewardGiftCard implements ShouldQueue
{
    /**
     * ギフトカードを顧客へ提供
     */
    public function handle(OrderCreated $event): void
    {
        // ...
    }

    /**
     * リスナをキューへ投入するかを決定
     */
    public function shouldQueue(OrderCreated $event): bool
    {
        return $event->order->subtotal >= 5000;
    }
}

キューの手作業操作Manually Interacting With the Queue

リスナの基になるキュージョブのdeleteメソッドとreleaseメソッドへ手作業でアクセスする必要がある場合は、Illuminate\Queue\InteractsWithQueueトレイトを使用してアクセスできます。このトレイトは、生成したリスナにはデフォルトでインポートされ、以下のメソッドへのアクセスを提供します。If you need to manually access the listener's underlying queue job's delete and release methods, you may do so using the Illuminate\Queue\InteractsWithQueue trait. This trait is imported by default on generated listeners and provides access to these methods:

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * イベントの処理
     */
    public function handle(OrderShipped $event): void
    {
        if (true) {
            $this->release(30);
        }
    }
}

キュー投入するイベントリスナとデータベーストランザクションQueued Event Listeners and Database Transactions

キュー投入したリスナがデータベーストランザクション内でディスパッチされると、データベーストランザクションがコミットされる前にキューによって処理される場合があります。これが発生した場合、データベーストランザクション中にモデルまたはデータベースレコードに加えた更新は、データベースにまだ反映されていない可能性があります。さらに、トランザクション内で作成されたモデルまたはデータベースレコードは、データベースに存在しない可能性があります。リスナがこれらのモデルに依存している場合、キューに入れられたリスナをディスパッチするジョブの処理時に予期しないエラーが発生する可能性があります。When queued listeners are dispatched within database transactions, they may be processed by the queue before the database transaction has committed. When this happens, any updates you have made to models or database records during the database transaction may not yet be reflected in the database. In addition, any models or database records created within the transaction may not exist in the database. If your listener depends on these models, unexpected errors can occur when the job that dispatches the queued listener is processed.

キュー接続のafter_commit設定オプションがfalseに設定されている場合でも、リスナクラスでShouldQueueAfterCommitインターフェイスを実装することにより、開いているすべてのデータベーストランザクションがコミットされた後に、特定のキューに入れられたリスナをディスパッチする必要があることを示すことができます。If your queue connection's after_commit configuration option is set to false, you may still indicate that a particular queued listener should be dispatched after all open database transactions have been committed by implementing the ShouldQueueAfterCommit interface on the listener class:

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueueAfterCommit;
use Illuminate\Queue\InteractsWithQueue;

class SendShipmentNotification implements ShouldQueueAfterCommit
{
    use InteractsWithQueue;
}

lightbulb Note: こうした問題の回避方法の詳細は、キュー投入されるジョブとデータベーストランザクションに関するドキュメントを確認してください。[!NOTE]
To learn more about working around these issues, please review the documentation regarding queued jobs and database transactions[/docs/{{version}}/queues#jobs-and-database-transactions].

失敗したジョブの処理Handling Failed Jobs

キュー投入したイベントリスナが失敗する場合があります。キュー投入したリスナがキューワーカーによって定義された最大試行回数を超えると、リスナ上のfailedメソッドが呼び出されます。failedメソッドは、失敗の原因となったイベントインスタンスとThrowableを受け取ります。Sometimes your queued event listeners may fail. If the queued listener exceeds the maximum number of attempts as defined by your queue worker, the failed method will be called on your listener. The failed method receives the event instance and the Throwable that caused the failure:

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Throwable;

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * イベントの処理
     */
    public function handle(OrderShipped $event): void
    {
        // ...
    }

    /**
     * ジョブの失敗を処理
     */
    public function failed(OrderShipped $event, Throwable $exception): void
    {
        // ...
    }
}

キュー投入したリスナの最大試行回数の指定Specifying Queued Listener Maximum Attempts

キュー投入したリスナの１つでエラーが発生した場合、リスナが無期限に再試行し続けることを皆さんも望まないでしょう。そのため、Laravelはリスナを試行できる回数または期間を指定するさまざまな方法を提供しています。If one of your queued listeners is encountering an error, you likely do not want it to keep retrying indefinitely. Therefore, Laravel provides various ways to specify how many times or for how long a listener may be attempted.

リスナクラスで$trysプロパティを定義して、リスナが失敗したと見なされるまでに試行できる回数を指定できます。You may define a $tries property on your listener class to specify how many times the listener may be attempted before it is considered to have failed:

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * キュー投入したリスナが試行される回数
     *
     * @var int
     */
    public $tries = 5;
}

リスナが失敗するまでに試行できる回数を定義する代わりに、リスナをそれ以上試行しない時間を定義することもできます。これにより、リスナは特定の時間枠内で何度でも試行します。リスナの試行最長時間を定義するには、リスナクラスにretryUntilメソッドを追加します。このメソッドはDateTimeインスタンスを返す必要があります:As an alternative to defining how many times a listener may be attempted before it fails, you may define a time at which the listener should no longer be attempted. This allows a listener to be attempted any number of times within a given time frame. To define the time at which a listener should no longer be attempted, add a retryUntil method to your listener class. This method should return a DateTime instance:

use DateTime;

/**
 * リスナタイムアウト時間を決定
 */
public function retryUntil(): DateTime
{
    return now()->addMinutes(5);
}

キュー投入済みリスナの再試行待ち秒数指定Specifying Queued Listener Backoff

例外が発生したリスナを再試行する前に、Laravelが何秒待つかを設定したい場合は、リスナクラスへbackoffプロパティを定義してください。If you would like to configure how many seconds Laravel should wait before retrying a listener that has encountered an exception, you may do so by defining a backoff property on your listener class:

/**
 * キュー投入済みリスナを再試行する前に何秒待つか
 *
 * @var int
 */
public $backoff = 3;

リスナの再試行待ち時間を決定するため、より複雑なロジックが必要な場合は、リスナクラスにbackoffメソッドを定義してください。If you require more complex logic for determining the listeners's backoff time, you may define a backoff method on your listener class:

/**
 * キュー投入済みリスナを再試行するまで待つ秒数の計算
 */
public function backoff(): int
{
    return 3;
}

backoffメソッドからバックオフ値の配列を返すことで、簡単に「指数関数的」な待ち秒数が設定できます。この例では、リトライの遅延は最初のリトライで１秒、２回目のリトライで５秒、３回目のリトライで１０秒、それ以降もリトライが残っている場合は毎回１０秒となります：You may easily configure "exponential" backoffs by returning an array of backoff values from the backoff method. In this example, the retry delay will be 1 second for the first retry, 5 seconds for the second retry, 10 seconds for the third retry, and 10 seconds for every subsequent retry if there are more attempts remaining:

/**
 * キュー投入済みリスナを再試行するまで待つ秒数の計算
 *
 * @return array<int, int>
 */
public function backoff(): array
{
    return [1, 5, 10];
}

イベント発行Dispatching Events

イベントをディスパッチするには、イベントで静的なdispatchメソッドを呼び出します。このメソッドはIlluminate\Foundation\Events\Dispatchableトレイトにより、イベントで使用可能になります。dispatchメソッドに渡された引数はすべて、イベントのコンストラクタへ渡されます。To dispatch an event, you may call the static dispatch method on the event. This method is made available on the event by the Illuminate\Foundation\Events\Dispatchable trait. Any arguments passed to the dispatch method will be passed to the event's constructor:

<?php

namespace App\Http\Controllers;

use App\Events\OrderShipped;
use App\Http\Controllers\Controller;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class OrderShipmentController extends Controller
{
    /**
     * 指定注文を発送
     */
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);

        // 注文出荷ロジック…

        OrderShipped::dispatch($order);

        return redirect('/orders');
    }
}

条件付きでイベントをディスパッチしたい場合は、dispatchIfかdispatchUnlessメソッドが使用できます。If you would like to conditionally dispatch an event, you may use the dispatchIf and dispatchUnless methods:

OrderShipped::dispatchIf($condition, $order);

OrderShipped::dispatchUnless($condition, $order);

lightbulb Note: テストの際、あるイベントが実際にリスナを起動することなくディスパッチされたことをアサートできると役立ちます。Laravelに組み込み済みのテストヘルパは、これを簡単に実現します。[!NOTE]
When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's built-in testing helpers[#testing] make it a cinch.

データベーストランザクション後のイベント発行Dispatching Events After Database Transactions

アクティブなデータベーストランザクションをコミットした後にのみ、イベントを発行するようにLaravelへ指示したい場合があると思います。そのためには、イベントクラスでShouldDispatchAfterCommitインターフェイスを実装します。Sometimes, you may want to instruct Laravel to only dispatch an event after the active database transaction has committed. To do so, you may implement the ShouldDispatchAfterCommit interface on the event class.

このインターフェイスは、現在のデータベーストランザクションがコミットされるまで、イベントを発行しないようにLaravelへ指示するものです。トランザクションが失敗した場合は、イベントを破棄します。イベントを発行した時にデータベーストランザクションが進行中でなければ、イベントを直ちに発行します。This interface instructs Laravel to not dispatch the event until the current database transaction is committed. If the transaction fails, the event will be discarded. If no database transaction is in progress when the event is dispatched, the event will be dispatched immediately:

<?php

namespace App\Events;

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

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

    /**
     * 新しいイベントインスタンスの生成
     */
    public function __construct(
        public Order $order,
    ) {}
}

イベントサブスクライバEvent Subscribers

イベントサブスクライバの記述Writing Event Subscribers

イベントサブスクライバは、サブスクライバクラス自体から複数のイベントを購読できるクラスであり、単一のクラス内で複数のイベントハンドラを定義できます。サブスクライバは、イベントディスパッチャーインスタンスを渡すsubscribeメソッドを定義する必要があります。特定のディスパッチャ上のlistenメソッドを呼び出して、イベントリスナを登録します。Event subscribers are classes that may subscribe to multiple events from within the subscriber class itself, allowing you to define several event handlers within a single class. Subscribers should define a subscribe method, which will be passed an event dispatcher instance. You may call the listen method on the given dispatcher to register event listeners:

<?php

namespace App\Listeners;

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

class UserEventSubscriber
{
    /**
     * ユーザーログインイベントの処理
     */
    public function handleUserLogin(Login $event): void {}

    /**
     * ユーザーログアウトイベントの処理
     */
    public function handleUserLogout(Logout $event): void {}

    /**
     * サブスクライバのリスナを登録
     */
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(
            Login::class,
            [UserEventSubscriber::class, 'handleUserLogin']
        );

        $events->listen(
            Logout::class,
            [UserEventSubscriber::class, 'handleUserLogout']
        );
    }
}

イベントリスナのメソッドがサブスクライバ自身の中で定義されている場合は、サブスクライバのsubscribeメソッドからメソッド名とイベントの配列を返す方が便利でしょう。Laravelはイベントリスナを登録する際に、サブスクライバのクラス名を自動的に決定します。If your event listener methods are defined within the subscriber itself, you may find it more convenient to return an array of events and method names from the subscriber's subscribe method. Laravel will automatically determine the subscriber's class name when registering the event listeners:

<?php

namespace App\Listeners;

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

class UserEventSubscriber
{
    /**
     * ユーザーログインイベントの処理
     */
    public function handleUserLogin(Login $event): void {}

    /**
     * ユーザーログアウトイベントの処理
     */
    public function handleUserLogout(Logout $event): void {}

    /**
     * サブスクライバのリスナを登録
     *
     * @return array<string, string>
     */
    public function subscribe(Dispatcher $events): array
    {
        return [
            Login::class => 'handleUserLogin',
            Logout::class => 'handleUserLogout',
        ];
    }
}

イベントサブスクライバの登録Registering Event Subscribers

サブスクライバを書き終えたら、Laravelのイベント検出規約に従っていれば、Laravelは自動的にサブスクライバ内へハンドラメソッドを登録します。そうでない場合は、Eventファサードのsubscribeメソッドを使用して、手作業でサブスクライバを登録します。通常、これはアプリケーションのAppServiceProviderのbootメソッド内で行います。After writing the subscriber, Laravel will automatically register handler methods within the subscriber if they follow Laravel's event discovery conventions[#event-discovery]. Otherwise, you may manually register your subscriber using the subscribe method of the Event facade. Typically, this should be done within the boot method of your application's AppServiceProvider:

<?php

namespace App\Providers;

use App\Listeners\UserEventSubscriber;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * アプリケーションの全サービスの初期起動処理
     */
    public function boot(): void
    {
        Event::subscribe(UserEventSubscriber::class);
    }
}

TestingTesting

イベントをディスパッチするコードをテストする場合、イベントのリスナを実際に実行しないように、Laravelへ指示したい場合があるでしょう。リスナのコードは、対応するイベントをディスパッチするコードとは別に、直接テストすることができるからです。もちろん、リスナ自体をテストするには、リスナインスタンスをインスタンス化し、テスト内で直接handleメソッドを呼び出せます。When testing code that dispatches events, you may wish to instruct Laravel to not actually execute the event's listeners, since the listener's code can be tested directly and separately of the code that dispatches the corresponding event. Of course, to test the listener itself, you may instantiate a listener instance and invoke the handle method directly in your test.

Eventファサードのfakeメソッドを使用し、リスナを実行しないでテスト対象のコードを実行し、assertDispatched、assertNotDispatched、assertNothingDispatchedメソッドを使用してアプリケーションがどのイベントをディスパッチするかをアサートできます。Using the Event facade's fake method, you may prevent listeners from executing, execute the code under test, and then assert which events were dispatched by your application using the assertDispatched, assertNotDispatched, and assertNothingDispatched methods:

<?php

use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;

test('orders can be shipped', function () {
    Event::fake();

    // 注文の発送処理…

    // 一つのイベントをディスパッチするのをアサート
    Event::assertDispatched(OrderShipped::class);

    // 一つのイベントを２回ディスパッチするのをアサート
    Event::assertDispatched(OrderShipped::class, 2);

    // あるイベントをディスパッチしないことをアサート
    Event::assertNotDispatched(OrderFailedToShip::class);

    // イベントを全くディスパッチしないことをアサート
    Event::assertNothingDispatched();
});

<?php

namespace Tests\Feature;

use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    /**
     * 注文発送のテスト
     */
    public function test_orders_can_be_shipped(): void
    {
        Event::fake();

        // 注文の発送処理…

        // 一つのイベントをディスパッチするのをアサート
        Event::assertDispatched(OrderShipped::class);

        // 一つのイベントを２回ディスパッチするのをアサート
        Event::assertDispatched(OrderShipped::class, 2);

        // あるイベントをディスパッチしないことをアサート
        Event::assertNotDispatched(OrderFailedToShip::class);

        // イベントを全くディスパッチしないことをアサート
        Event::assertNothingDispatched();
    }
}

クロージャをassertDispatchedやassertNotDispatchedメソッドに渡すと、指定したその「真理値テスト」に合格するイベントが、ディスパッチされたことをアサートできます。指定真理値テストにパスするイベントが最低１つディスパッチされた場合、アサートは成功します。You may pass a closure to the assertDispatched or assertNotDispatched methods in order to assert that an event was dispatched that passes a given "truth test". If at least one event was dispatched that passes the given truth test then the assertion will be successful:

Event::assertDispatched(function (OrderShipped $event) use ($order) {
    return $event->order->id === $order->id;
});

イベントリスナが指定イベントをリッスンしていることを単純にアサートしたい場合は、assertListeningメソッドを使用してください。If you would simply like to assert that an event listener is listening to a given event, you may use the assertListening method:

Event::assertListening(
    OrderShipped::class,
    SendShipmentNotification::class
);

warning Warning! Event::fake()を呼び出した後は、イベントリスナが実行されることはありません。したがって、テストがイベントに依存するモデルファクトリを使用している場合、例えば、モデルのcreatingイベント中にUUIDを作成する場合、ファクトリを使用した後に、Event::fake()を呼び出す必要があります。[!WARNING]
After calling Event::fake(), no event listeners will be executed. So, if your tests use model factories that rely on events, such as creating a UUID during a model's creating event, you should call Event::fake() after using your factories.

イベントサブセットのFakeFaking a Subset of Events

特定のイベントセットに対してのみイベントリスナをFakeしたい場合は、fakeまたはfakeForメソッドへそれらを渡してください。If you only want to fake event listeners for a specific set of events, you may pass them to the fake or fakeFor method:

test('orders can be processed', function () {
    Event::fake([
        OrderCreated::class,
    ]);

    $order = Order::factory()->create();

    Event::assertDispatched(OrderCreated::class);

    // 他のイベントは普段通りディスパッチする
    $order->update([...]);
});

/**
 * 注文発送のテスト
 */
public function test_orders_can_be_processed(): void
{
    Event::fake([
        OrderCreated::class,
    ]);

    $order = Order::factory()->create();

    Event::assertDispatched(OrderCreated::class);

    // 他のイベントは普段通りディスパッチする
    $order->update([...]);
}

exceptメソッドを使用すると、指定イベント以外のすべてのイベントをFakeできます。You may fake all events except for a set of specified events using the except method:

Event::fake()->except([
    OrderCreated::class,
]);

イベントFakeのスコープScoped Event Fakes

テストの一部分だけでイベントリスナをFakeしたい場合は、fakeForメソッドを使用します。If you only want to fake event listeners for a portion of your test, you may use the fakeFor method:

<?php

use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;

test('orders can be processed', function () {
    $order = Event::fakeFor(function () {
        $order = Order::factory()->create();

        Event::assertDispatched(OrderCreated::class);

        return $order;
    });

    // イベントを通常通りディスパッチし、オブザーバが実行される
    $order->update([...]);
});

<?php

namespace Tests\Feature;

use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    /**
     * 注文処理のテスト
     */
    public function test_orders_can_be_processed(): void
    {
        $order = Event::fakeFor(function () {
            $order = Order::factory()->create();

            Event::assertDispatched(OrderCreated::class);

            return $order;
        });

        // イベントを通常通りディスパッチし、オブザーバが実行される
        $order->update([...])
    }
}