Laravel 7.x イベント

イントロダクションIntroduction

Laravelのイベントはシンプルなオブザーバの実装で、アプリケーションで発生するさまざまなイベントを購読し、リッスンするために使用します。イベントクラスは通常、app/Eventsディレクトリに保存されます。一方、リスナはapp/Listenersディレクトリへ保存されます。アプリケーションに両ディレクトリが存在しなくても、心配ありません。Artisanコンソールコマンドを使い、イベントとリスナを生成するとき、ディレクトリも生成されます。Laravel's events provide a simple observer implementation, allowing you to subscribe and listen for various events that occur in 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, since they will be created for you as you generate events and listeners using Artisan console commands.

一つのイベントは、互いに依存していない複数のリスナに紐付けられますので、アプリケーションのさまざまな要素を独立させるための良い手段として活用できます。たとえば、注文を配送するごとにSlack通知をユーザーへ届けたいとします。注文の処理コードとSlackの通知コードを結合する代わりに、OrderShippedイベントを発行し、リスナがそれを受け取り、Slack通知へ変換するように実装できます。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 OrderShipped event, which a listener can receive and transform into a Slack notification.

イベント／リスナ登録Registering Events & Listeners

Laravelアプリケーションに含まれているEventServiceProviderは、イベントリスナを全部登録するために便利な場所を提供しています。listenプロパティは全イベント（キー）とリスナ（値）で構成されている配列です。アプリケーションで必要とされているイベントをこの配列に好きなだけ追加できます。例として、OrderShippedイベントを追加してみましょう。The EventServiceProvider included with your Laravel application provides a convenient place to register all of your application's event listeners. The listen property contains an array of all events (keys) and their listeners (values). You may add as many events to this array as your application requires. For example, let's add a OrderShipped event:

/**
 * アプリケーションのイベントリスナをマップ
 *
 * @var array
 */
protected $listen = [
    'App\Events\OrderShipped' => [
        'App\Listeners\SendShipmentNotification',
    ],
];

イベント／リスナ生成Generating Events & Listeners

毎回ハンドラやリスナを作成するのは、当然のことながら手間がかかります。代わりにハンドラとリスナをEventServiceProviderに追加し、event:generateコマンドを使いましょう。このコマンドはEventServiceProviderにリストしてあるイベントやリスナを生成してくれます。既存のイベントとハンドラには、変更を加えません。Of course, manually creating the files for each event and listener is cumbersome. Instead, add listeners and events to your EventServiceProvider and use the event:generate command. This command will generate any events or listeners that are listed in your EventServiceProvider. Events and listeners that already exist will be left untouched:

php artisan event:generate

イベントの手動登録Manually Registering Events

通常イベントは、EventServiceProviderの$listen配列により登録するべきです。しかし、EventServiceProviderのbootメソッドの中で、クロージャベースリスナを登録できます。Typically, events should be registered via the EventServiceProvider $listen array; however, you may also register Closure based events manually in the boot method of your EventServiceProvider:

/**
 * アプリケーションの他のイベントを登録する
 *
 * @return void
 */
public function boot()
{
    parent::boot();

    Event::listen('event.name', function ($foo, $bar) {
        //
    });
}

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

登録したリスナが、*をワイルドカードパラメータとして使用している場合、同じリスナで複数のイベントを捕捉できます。ワイルドカードリスナは、イベント全体のデータ配列を最初の引数として、イベントデータ全体を第２引数として受け取ります。You may even register listeners using the * 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 ($eventName, array $data) {
    //
});

イベントディスカバリEvent Discovery

EventServiceProviderの$listen配列へ、自分でイベントとリスナを登録する代わりに、自動的にイベントを検出させることができます。イベントディスカバリを有効にすると、LaravelはアプリケーションのListenersディレクトリをスキャンし、自動的にイベントとリスナを見つけ出して登録します。さらに、EventServiceProviderで明示的に定義されたイベントリストも今まで通りに登録します。Instead of registering events and listeners manually in the $listen array of the EventServiceProvider, you can enable automatic event discovery. When event discovery is enabled, Laravel will automatically find and register your events and listeners by scanning your application's Listeners directory. In addition, any explicitly defined events listed in the EventServiceProvider will still be registered.

Laravelはリフレクションを使いリスナクラスをスキャンし、イベントリスナを見つけます。Laravelはhandleで始まるイベントリスナクラスメソッドを見つけると、そのメソッド引数のタイプヒントで示すイベントに対する、イベントリスナとしてメソッドを登録します。Laravel finds event listeners by scanning the listener classes using reflection. When Laravel finds any listener class method that begins with handle, 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 SendPodcastProcessedNotification
{
    /**
     * 指定イベントの処理
     *
     * @param  \App\Events\PodcastProcessed
     * @return void
     */
    public function handle(PodcastProcessed $event)
    {
        //
    }
}

イベントディスカバリはデフォルトで無効になっています。アプリケーションのEventServiceProviderにあるshouldDiscoverEventsをオーバーライドすることで、有効にできます。Event discovery is disabled by default, but you can enable it by overriding the shouldDiscoverEvents method of your application's EventServiceProvider:

/**
 * イベントとリスナを自動的に検出するか指定
 *
 * @return bool
 */
public function shouldDiscoverEvents()
{
    return true;
}

アプリケーションのListenersディレクトリ中の全リスナが、デフォルトでスキャンされます。スキャンする追加のディレクトリを定義したい場合は、EventServiceProviderのdiscoverEventsWithinをオーバーライドしてください。By default, all listeners within your application's Listeners directory will be scanned. If you would like to define additional directories to scan, you may override the discoverEventsWithin method in your EventServiceProvider:

/**
 * イベントを見つけるために使用するリスナディレクトリの取得
 *
 * @return array
 */
protected function discoverEventsWithin()
{
    return [
        $this->app->path('Listeners'),
    ];
}

実働時はリクエストのたびに、すべてのリスナをフレームワークにスキャンさせるのは好ましくないでしょう。アプリケーションのイベントとリスナの全目録をキャッシュする、event:cache Artisanコマンドを実行すべきです。この目録はフレームワークによるイベント登録処理をスピードアップするために使用されます。event:clearコマンドにより、このキャッシュは破棄されます。In production, you likely do not want the framework to scan all of your listeners on every request. Therefore, during your deployment process, you should run the event:cache Artisan command to cache a manifest of all of your application's events and listeners. 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 cache.

lightbulb">Tip!! event:listコマンドで、アプリケーションに登録されたすべてのイベントとリスナを一覧表示できます。{tip} The event:list command may be used to display a list of all events and listeners registered by your application.

イベント定義Defining Events

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

<?php

namespace App\Events;

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

class OrderShipped
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $order;

    /**
     * 新しいイベントインスタンスの生成
     *
     * @param  \App\Order  $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }
}

ご覧の通り、このクラスはロジックを含みません。購入されたOrderオブジェクトのための、コンテナです。イベントオブジェクトがPHPのserialize関数でシリアライズされる場合でも、EloquentモデルをイベントがuseしているSerializesModelsトレイトが優雅にシリアライズします。As you can see, this event class contains no logic. It is a container for the 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.

リスナの定義Defining Listeners

次にサンプルイベントのリスナを取り上げましょう。イベントリスナはイベントインスタンスをhandleメソッドで受け取ります。event:generateコマンドは自動的に適切なイベントクラスをインポートし、handleメソッドのイベントのタイプヒントを指定します。そのイベントに対応するため必要なロジックをhandleメソッドで実行してください。Next, let's take a look at the listener for our example event. Event listeners receive the event instance in their handle method. The event:generate command will automatically import the proper event class and type-hint the event on 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
{
    /**
     * イベントリスナ生成
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * イベントの処理
     *
     * @param  \App\Events\OrderShipped  $event
     * @return void
     */
    public function handle(OrderShipped $event)
    {
        // $event->orderにより、注文へアクセス…
    }
}

lightbulb">Tip!! イベントリスナでも、必要な依存をコンストラクターのタイプヒントで指定できます。イベントリスナはすべてLaravelのサービスコンテナで依存解決されるので、依存は自動的に注入されます。{tip} 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 e-mail or making an HTTP request. Before getting started with queued listeners, make sure to configure your queue[/docs/{{version}}/queues] and start a queue listener on your server or local development environment.

リスナをキュー投入するように指定するには、ShouldQueueインターフェイスをリスナクラスに追加します。event:generate Artisanコマンドにより生成したリスナには、すでにこのインターフェイスが現在の名前空間下にインポートされていますので、すぐに使用できます。To specify that a listener should be queued, add the ShouldQueue interface to the listener class. Listeners generated by the event:generate Artisan command 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 this listener is called for an event, it will be automatically 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 & Queue Name

イベントリスナのキュー接続とキュー名、イベントリスナのキュー遅延時間をカスタマイズしたい場合は、$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;
}

実行時のリスナのキューを定義したい場合は、リスナ上にviaQueueメソッドを定義してください。If you would like to define the listener's queue at runtime, you may define a viaQueue method on the listener:

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

条件付きリスナのキュー投入Conditionally Queueing Listeners

あるデータが存在する場合のみ、実行時にリスナをキューすると判断する必要が起きる場合もあります。そのためにはshouldQueueメソッドをリスナへ追加し、そのリスナがキューされるかどうかを決めます。shouldQueueがfalseを返すとそのリスナは実行されません。Sometimes, you may need to determine whether a listener should be queued based on some data that's 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 executed:

<?php

namespace App\Listeners;

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

class RewardGiftCard implements ShouldQueue
{
    /**
     * 顧客にギフトカードを贈る
     *
     * @param  \App\Events\OrderPlaced  $event
     * @return void
     */
    public function handle(OrderPlaced $event)
    {
        //
    }

    /**
     * リスナがキューされるかどうかを決める
     *
     * @param  \App\Events\OrderPlaced  $event
     * @return bool
     */
    public function shouldQueue(OrderPlaced $event)
    {
        return $event->order->subtotal >= 5000;
    }
}

キューへの任意アクセスManually Accessing 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;

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

失敗したジョブの取り扱いHandling Failed Jobs

キュー投入したイベントリスナはときどき落ちることがあります。キューワーカにより定義された最大試行回数を超え、キュー済みのリスナが実行されると、リスナのfailedメソッドが実行されます。failedメソッドはイベントインスタンスと落ちた原因の例外を引数に受け取ります。Sometimes your queued event listeners may fail. If 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 exception that caused the failure:

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * イベントの処理
     *
     * @param  \App\Events\OrderShipped  $event
     * @return void
     */
    public function handle(OrderShipped $event)
    {
        //
    }

    /**
     * 失敗したジョブの処理
     *
     * @param  \App\Events\OrderShipped  $event
     * @param  \Throwable  $exception
     * @return void
     */
    public function failed(OrderShipped $event, $exception)
    {
        //
    }
}

イベントの発行Dispatching Events

イベントを発行するには、eventヘルパにイベントのインスタンスを渡してください。このヘルパは登録済みのリスナ全部へイベントをディスパッチします。eventヘルパはグローバルに使用できますので、アプリケーションのどこからでも呼び出すことができます。To dispatch an event, you may pass an instance of the event to the event helper. The helper will dispatch the event to all of its registered listeners. Since the event helper is globally available, you may call it from anywhere in your application:

<?php

namespace App\Http\Controllers;

use App\Events\OrderShipped;
use App\Http\Controllers\Controller;
use App\Order;

class OrderController extends Controller
{
    /**
     * 指定した注文を発送
     *
     * @param  int  $orderId
     * @return Response
     */
    public function ship($orderId)
    {
        $order = Order::findOrFail($orderId);

        // 注文発送ロジック…

        event(new OrderShipped($order));
    }
}

もしくは、イベントがIlluminate\Foundation\Events\Dispatchableトレイトを使用していれば、そのイベントの静的dispatchメソッドを呼び出せます。dispatchメソッドへ渡したすべての引数は、そのイベントのコンストラクタへ渡されます。Alternatively, if your event uses the Illuminate\Foundation\Events\Dispatchable trait, you may call the static dispatch method on the event. Any arguments passed to the dispatch method will be passed to the event's constructor:

OrderShipped::dispatch($order);

lightbulb">Tip!! テスト時は実際にリスナを起動せずに、正しいイベントがディスパッチされたことをアサートできると便利です。Laravelに組み込まれたテストヘルパで簡単に行なえます。{tip} When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's built-in testing helpers[/docs/{{version}}/mocking#event-fake] makes it a cinch.

イベントEvent Subscribers

イベント購読プログラミングWriting Event Subscribers

イベント購読クラスは、その内部で複数のイベントを購読でき、一つのクラスで複数のイベントハンドラを定義できます。購読クラスは、イベントディスパッチャインスタンスを受け取る、subscribeメソッドを定義する必要があります。イベントリスナを登録するには、渡されたディスパッチャのlistenメソッドを呼び出します。Event subscribers are classes that may subscribe to multiple events from within the 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;

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

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

    /**
     * 購読するリスナの登録
     *
     * @param  \Illuminate\Events\Dispatcher  $events
     */
    public function subscribe($events)
    {
        $events->listen(
            'Illuminate\Auth\Events\Login',
            'App\Listeners\UserEventSubscriber@handleUserLogin'
        );

        $events->listen(
            'Illuminate\Auth\Events\Logout',
            'App\Listeners\UserEventSubscriber@handleUserLogout'
        );
    }
}

イベント購読登録Registering Event Subscribers

購読クラスを書いたら、イベントディスパッチャへ登録できる準備が整いました。EventServiceProviderの$subscribeプロパティを使用し、購読クラスを登録します。例として、UserEventSubscriberをリストに追加してみましょう。After writing the subscriber, you are ready to register it with the event dispatcher. You may register subscribers using the $subscribe property on the EventServiceProvider. For example, let's add the UserEventSubscriber to the list:

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * アプリケーションのイベントリスナをマップ
     *
     * @var array
     */
    protected $listen = [
        //
    ];

    /**
     * 登録する購読クラス
     *
     * @var array
     */
    protected $subscribe = [
        'App\Listeners\UserEventSubscriber',
    ];
}