Laravel 7.x 通知

イントロダクション

メール送信に加え、LaravelはSMS（以前、Nexmoとして知られていたVonageを使用）、Slackなどの、さまざまな複数チャンネルへ渡る通知をサポートしています。通知はWebインターフェイスで表示できるように、データベースに保存することもできます。

通常、通知はアプリケーションで何かが起きたことをユーザーへ知らせる、短い情報メッセージです。たとえば、課金アプリを作成しているなら、メールとSMSチャンネルで「課金支払い」を送信できます。

通知の作成

Laravelの各通知は、（通常、app/Notificationsディレクトリに設置される）クラスにより表されます。このディレクトリがアプリケーションで見つからなくても、心配ありません。make:notification Artisanコマンドを実行すると、作成されます。

php artisan make:notification InvoicePaid

このコマンドにより、真新しい通知クラスが、app/Notificationsディレクトリに生成されます。各通知クラスはviaメソッドと、特定のチャンネルに最適化したメッセージへ変換する、いくつかのメッセージ構築メソッド（toMail、toDatabaseなど）を含んでいます。

通知の送信

Notifiableトレイトの使用

通知は２つの方法で送信されます。Notifiableトレイトのnotifyメソッドか、Notificationファサードを使う方法です。最初に、トレイトを見ていきましょう。

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;
}

このトレイトは、デフォルトのApp\Userモデルで使用されており、通知を送るためのnotifyメソッドを一つ含んでいます。notifyメソッドは通知インスタンスを受け取ります。

use App\Notifications\InvoicePaid;

$user->notify(new InvoicePaid($invoice));

Tip!! みなさんのどんなモデルであっても、Illuminate\Notifications\Notifiableトレイトを使えることを覚えておきましょう。使用はUserモデルだけに限定されているわけでありません。

Notificationファサードの使用

ほかに、Notificationファサードを使用し、通知を送る方法もあります。これは主にユーザーコレクションのような、複数の通知可能エンティティに対し、通知する場合に便利です。ファサードを使い通知するには、sendメソッドへ通知可能エンティティ全部と、通知インスタンスを渡します。

Notification::send($users, new InvoicePaid($invoice));

配信チャンネルの指定

通知を配信するチャンネルを指定するため、すべての通知クラスはviaメソッドを持っています。通知はmail、database、broadcast、nexmo、slackへ送れるようになっています。

Tip!! TelegramやPusherのような、他の配信チャンネルを利用したい場合は、コミュニティが管理している、Laravel Notification Channels websiteをご覧ください。

viaメソッドは、通知を送っているクラスのインスタンスである、$notifiableインスタンスを引数に受け取ります。$notifiableを使い、通知をどこに配信するチャンネルなのかを判定できます。

/**
 * 通知の配信チャンネルを取得
 *
 * @param  mixed  $notifiable
 * @return array
 */
public function via($notifiable)
{
    return $notifiable->prefers_sms ? ['nexmo'] : ['mail', 'database'];
}

通知のキューイング

Note: 通知のキューイングを行う前に、キューを設定し、ワーカを起動する必要があります。

通知の送信には時間が取られます。とくにそのチャンネルが通知を配信するために、外部のAPIを呼び出す必要がある場合はとくにです。アプリケーションのレスポンスタイムを向上させるには、クラスにShouldQueueインターフェイスと、Queueableトレイトを追加し、キューイングしましょう。このインターフェイスとトレイトは、make:notificationを使用して生成された全通知でインポート済みですから、すぐに通知クラスに追加できます。

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification implements ShouldQueue
{
    use Queueable;

    // ...
}

ShouldQueueインターフェイスを通知クラスへ追加したら、通常通りに送信してください。LaravelはクラスのShouldQueueインターフェイスを見つけ、自動的に通知の配信をキューへ投入します。

$user->notify(new InvoicePaid($invoice));

通知の配信を遅らせたい場合、delayメソッドを通知のインスタンスへチェーンしてください。

$when = now()->addMinutes(10);

$user->notify((new InvoicePaid($invoice))->delay($when));

通知チャンネルキューのカスタマイズ

各通知チャンネルが使用し、その通知がサポートしている特定のキューを指定する場合、通知へviaQueuesメソッドを定義してください。このメソッドはチャンネル名／キュー名のペアの配列を返してください。

/**
 * 各通知チャンネルで使用するキューを判断。
 *
 * @return array
 */
public function viaQueues()
{
    return [
        'mail' => 'mail-queue',
        'slack' => 'slack-queue',
    ];
}

オンデマンド通知

場合により、アプリケーションの「ユーザー」として保存されていない誰かに対し、通知を送る必要が起き得ます。Notification::routeファサードメソッドを使い、通知を送る前にアドホックな通知ルーティング情報を指定できます。

Notification::route('mail', 'taylor@example.com')
            ->route('nexmo', '5555555555')
            ->route('slack', 'https://hooks.slack.com/services/...')
            ->notify(new InvoicePaid($invoice));

メール通知

メールメッセージのフォーマット

ある通知でメール送信をサポートする場合、通知クラスにtoMailメソッドを定義してください。このメソッドは、$notifiableエンティティを受け取り、Illuminate\Notifications\Messages\MailMessageインスタンスを返す必要があります。メールメッセージはテキスト行と、同時に"call to action"（アクションの呼び出し）を含むことでしょう。toMailメソッドの例を見てみましょう。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    $url = url('/invoice/'.$this->invoice->id);

    return (new MailMessage)
                ->greeting('Hello!')
                ->line('課金が支払われました。')
                ->action('インボイス確認', $url)
                ->line('私達のアプリケーションをご利用いただき、ありがとうございます。');
}

Tip!! toMailメソッドの中で、$this->invoice->idを使っていることに注意してください。通知メッセージを生成するために必要な情報は、どんなものでも通知のコンストラクタへ渡せます。

この例では、挨拶、テキスト行、アクションの呼び出し、別のテキスト行を登録しています。これらのメソッドは、小さなトランザクションメールをシンプルで素早くフォーマットする、MailMessageオブジェクトが提供しています。メールチャンネルはテンプレートにより、メッセージの構成物をきれいでレスポンシブなHTMLメールへ、変換します。平文メールも用意されます。以下はmailチャンネルにより生成されたメールの例です。I

Tip!! メール通知を行うときは、config/app.php設定ファイルのname値を確実に設定してください。この値は、メール通知メッセージのヘッダとフッタで使用されます。

他の通知フォーマットオプション

通知クラスの中にテキストの「行(line)」を定義する代わりに、通知メールをレンダーするためのカスタムテンプレートをviewメソッドを使い、指定できます。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    return (new MailMessage)->view(
        'emails.name', ['invoice' => $this->invoice]
    );
}

MailMessage:MailMessageのviewメソッドで指定する配列の第２要素としてビュー名を渡すことにより、メールメッセージの平文テキストビューを指定できます。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    return (new MailMessage)->view(
        ['emails.name.html', 'emails.name.plain'],
        ['invoice' => $this->invoice]
    );
}

さらに、toMailメソッドからMailableオブジェクトをそのまま返すこともできます。

use App\Mail\InvoicePaid as Mailable;

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return Mailable
 */
public function toMail($notifiable)
{
    return (new Mailable($this->invoice))->to($notifiable->email);
}

エラーメッセージ

ある通知はユーザーへエラーを知らせます。たとえば、課金の失敗です。メールメッセージがエラーに関するものであることを知らせるためには、メッセージ構築時にerrorメソッドを呼び出します。errorメソッドをメールメッセージで使用すると、アクション呼び出しボタンが青の代わりに赤で表示されます。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Message
 */
public function toMail($notifiable)
{
    return (new MailMessage)
                ->error()
                ->subject('Notification Subject')
                ->line('...');
}

送信者のカスタマイズ

デフォルトのメール送信者／Fromアドレスは、config/mail.php設定ファイルで定義されています。しかし、特定の通知でFromアドレスを指定する場合は、fromメソッドで指定します。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    return (new MailMessage)
                ->from('test@example.com', 'Example')
                ->line('...');
}

受信者のカスタマイズ

mailチャンネルを使い通知を送る場合、通知システムは自動的に通知エンティティでemailプロパティを探します。通知を配信するために使用するメールアドレスをカスタマイズするには、エンティティに対しrouteNotificationForMailメソッドを定義してください。

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * メールチャンネルに対する通知をルートする
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return array|string
     */
    public function routeNotificationForMail($notification)
    {
        // メールアドレスのみを返す場合
        return $this->email_address;

        // 名前とメールアドレスを返す場合
        return [$this->email_address => $this->name];
    }
}

件名のカスタマイズ

デフォルトのメール件名は、通知のクラス名を"title case"にフォーマットしたものです。ですから、InvoicePaidという通知クラス名は、Invoice Paidというメールの件名になります。メッセージの件名を明確に指定したい場合は、メッセージを構築時にsubjectメソッドを呼び出してください。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    return (new MailMessage)
                ->subject('Notification Subject')
                ->line('...');
}

Mailerのカスタマイズ

デフォルトのメール通知は、config/mail.php設定ファイルで定義されているデフォルトドライバにより送信されます。しかし、mailerメソッドをメッセージ組立時に呼び出せば、実行時に異なるメイラーを指定できます。

/**
 * 通知のメール表現を取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    return (new MailMessage)
                ->mailer('postmark')
                ->line('...');
}

テンプレートのカスタマイズ

通知パッケージのリソースをリソース公開することにより、メール通知で使用されるHTMLと平文テキストのテンプレートを変更することが可能です。次のコマンドを実行した後、メール通知のテンプレートはresources/views/vendor/notificationsディレクトリ下に作成されます。

php artisan vendor:publish --tag=laravel-notifications

メール通知のプレビュー

メール通知テンプレートをデザインしている時に、通常のBladeテンプレートのようにブラウザでメールメッセージをレンダーし、素早くプレビューできると便利です。そのため、Laravelはルートのクロージャやコントローラから直接メール通知を返すことにより、メールメッセージを生成できます。MailMessageが返されるとレンダーされ、ブラウザーへ表示されます。実際のメールアドレスへ送信することなく、デザインが素早くプレビューできます。

Route::get('mail', function () {
    $invoice = App\Invoice::find(1);

    return (new App\Notifications\InvoicePaid($invoice))
                ->toMail($invoice->user);
});

Markdownメール通知

Markdownメール通知により、事前に構築したテンプレートとメール通知のコンポーネントの利点をMailable中で利用できます。メッセージをMarkdownで記述すると、Laravelは美しいレスポンシブHTMLテンプレートをレンダーすると同時に、自動的に平文テキスト版も生成します。

メッセージ生成

対応するMarkdownテンプレートを指定し、Mailableを生成するには、make:notification Artisanコマンドを--markdownオプション付きで使用します。

php artisan make:notification InvoicePaid --markdown=mail.invoice.paid

他のメール通知すべてと同様に、Markdownテンプレートを使用する通知は、通知クラスにtoMailメソッドを定義する必要があります。しかし、lineとactionメソッドで通知を構成する代わりに、markdownメソッドを使用し、使用するMarkdownテンプレートの名前を指定します。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    $url = url('/invoice/'.$this->invoice->id);

    return (new MailMessage)
                ->subject('Invoice Paid')
                ->markdown('mail.invoice.paid', ['url' => $url]);
}

メッセージ記述

Markdownメール通知ではBladeコンポーネントとMarkdown記法が利用でき、メールメッセージを簡単に構築できると同時に、Laravelが用意している通知コンポーネントも活用できます。

@component('mail::message')
# 発送のお知らせ

商品が発送されました！

@component('mail::button', ['url' => $url])
注文の確認
@endcomponent

注文の確認<br>
{{ config('app.name') }} 様
@endcomponent

Buttonコンポーネント

ボタンコンポーネントは中央寄せのボタンリンクをレンダーします。このコンポーネントは引数として、urlとオプションのcolorを受け取ります。サポートしている色はblue、green、redです。メッセージに好きなだけのボタンコンポーネントを追加できます。

@component('mail::button', ['url' => $url, 'color' => 'green'])
注文の確認
@endcomponent

Panelコンポーネント

パネルコンポーネントは、メッセージの他の部分とは少し異なった背景色のパネルの中に、指定されたテキストブロックをレンダーします。これにより、指定するテキストに注目を集められます。

@component('mail::panel')
ここはパネルの内容です。
@endcomponent

Tableコンポーネント

テーブルコンポーネントは、MarkdownテーブルをHTMLテーブルへ変換します。このコンポーネントはMarkdownテーブルを内容として受け入れます。デフォルトのMarkdownテーブルの記法を使った、文字寄せをサポートしています。

@component('mail::table')
| Laravel       | テーブル      | 例       |
| ------------- |:-------------:| --------:|
| 第２カラムは  | 中央寄せ      | $10      |
| 第３カラムは  | 右寄せ        | $20      |
@endcomponent

コンポーネントカスタマイズ

自身のアプリケーション向きにカスタマイズできるように、Markdown通知コンポーネントはすべてエクスポートできます。コンポーネントをエクスポートするには、vendor:publish Artisanコマンドを使い、laravel-mailアセットをリソース公開します。

php artisan vendor:publish --tag=laravel-mail

このコマンドにより、resources/views/vendor/mailディレクトリ下にMarkdownメールコンポーネントがリソース公開されます。mailディレクトリ下に、htmlとtextディレクトリがあります。各ディレクトリは名前が示す形式で、利用できるコンポーネントすべてのレスポンシブなプレゼンテーションを持っています。これらのコンポーネントはお好きなよう、自由にカスタマイズしてください。

CSSのカスタマイズ

コンポーネントをエクスポートすると、resources/views/vendor/mail/html/themesディレクトリに、default.cssファイルが用意されます。このファイル中のCSSをカスタマイズすれば、Markdownメール通知変換後のHTML形式の中に、インラインCSSとして自動的に取り込まれます。

LaravelのMarkdownコンポーネントの完全に新しいテーマを作成したい場合は、html/themesディレクトリの中にCSSファイルを設置してください。CSSファイルに名前をつけ保存したら、mail設定ファイルのthemeオプションを新しいテーマの名前に更新してください。

個別の通知にカスタムテーマを使いたい場合は、通知のメールメッセージを構築する時に、themeメソッドを呼び出してください。themeメソッドの引数は、その通知送信で使用するテーマの名前です。

/**
 * 通知のメールプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return \Illuminate\Notifications\Messages\MailMessage
 */
public function toMail($notifiable)
{
    return (new MailMessage)
                ->theme('invoice')
                ->subject('Invoice Paid')
                ->markdown('mail.invoice.paid', ['url' => $url]);
}

データベース通知

事前要件

database通知チャンネルは、通知情報をデータベーステーブルへ保存します。このテーブルは通知タイプのような情報と同時に、通知を説明するカスタムJSONデータを含みます。

アプリケーションのユーザーインターフェイスで通知を表示するために、テーブルをクエリできます。しかし、その前に通知を保存するデータベーステーブルを作成する必要があります。実際のテーブルスキーマのマイグレーションを生成するために、notifications:tableを使用してください。

php artisan notifications:table

php artisan migrate

データベース通知のフォーマット

通知でデータベーステーブルへの保存をサポートする場合、通知クラスにtoDatabaseかtoArrayメソッドを定義する必要があります。このメソッドは$notifiableエンティティを受け取り、プレーンなPHP配列を返す必要があります。返された配列はJSONへエンコードされ、notificationsテーブルのdataカラムに保存されます。toArrayメソッドの例を見てみましょう。

/**
 * 通知の配列プレゼンテーションの取得
 *
 * @param  mixed  $notifiable
 * @return array
 */
public function toArray($notifiable)
{
    return [
        'invoice_id' => $this->invoice->id,
        'amount' => $this->invoice->amount,
    ];
}

toDatabase Vs. toArray

toArrayメソッドは、JavaScriptクライアントへどのデータをブロードキャストするかを決めるために、broadcastチャンネルでも使用されます。databaseとbroadcastチャンネルで、別々の配列プレゼンテーションを持ちたい場合は、toArrayメソッドの代わりに、toDatabaseメソッドを定義してください。

通知へのアクセス

通知をデータベースへ保存したら、通知エンティティから便利にアクセスできる方法が必要になります。LaravelのデフォルトApp\Userモデルに含まれている、Illuminate\Notifications\Notifiableトレイトは、notifications Eloquentリレーションを含んでおり、そのエンティティの通知を返します。通知を取得するために、他のEloquentリレーションと同様に、このメソッドにアクセスできます。デフォルトで、通知はcreated_atタイムスタンプでソートされます。

$user = App\User::find(1);

foreach ($user->notifications as $notification) {
    echo $notification->type;
}

「未読」の通知のみを取得したい場合は、unreadNotificationsリレーションシップを使います。この場合も、通知はcreated_atタイムスタンプでソートされます。

$user = App\User::find(1);

foreach ($user->unreadNotifications as $notification) {
    echo $notification->type;
}

Tip!! 通知にJavaScriptクライアントからアクセスするには、現在のユーザーのような、通知可能なエンティティに対する通知を返す、通知コントローラをアプリケーションに定義する必要があります。その後、JavaScriptクライエントから、コントローラのURIへHTTPリクエストを作成します。

Readとしての通知作成

通常、ユーザーが閲覧したときに、その通知を「既読」とマークするでしょう。Illuminate\Notifications\Notifiableトレイトは、通知のデータベースレコード上にある、read_atカラムを更新するmarkAsReadメソッドを提供しています。

$user = App\User::find(1);

foreach ($user->unreadNotifications as $notification) {
    $notification->markAsRead();
}

各通知をループで処理する代わりに、markAsReadメソッドを通知コレクションへ直接使用できます。

$user->unreadNotifications->markAsRead();

データベースから取得せずに、全通知に既読をマークするため、複数更新クエリを使用することもできます。

$user = App\User::find(1);

$user->unreadNotifications()->update(['read_at' => now()]);

テーブルエンティティから通知を削除するために、deleteを使うこともできます。

$user->notifications()->delete();

ブロードキャスト通知

事前要件

ブロードキャスト通知の前に、Laravelのイベントブロードキャストサービスを設定し、慣れておく必要があります。イベントブロードキャストは、JavaScriptクライアント側で、サーバサイドで発行されたLaravelイベントに対処する方法を提供しています。

ブロードキャスト通知のフォーマット

broadcastチャンネルは、リアルタイムでJavaScriptクライアントが通知を補足できるようにする、Laravelのイベントブロードキャストサービスを用い、通知をブロードキャストします。通知でブロードキャストをサポートする場合、通知クラスでtoBroadcastメソッドを定義ができます。このメソッドは$notifiableエンティティを受け取り、BroadcastMessageインスタンスを返す必要があります。toBroadcastメソッドが存在しない場合は、ブロードキャストするデータをまとめるためにtoArrayメソッドが使用されます。返されるデータはJSONへエンコードされ、JavaScriptクライアントへブロードキャストされます。toBroadcastメソッドの例を見てみましょう。

use Illuminate\Notifications\Messages\BroadcastMessage;

/**
 * 通知のブロードキャストプレゼンテーションの取得
 *
 * @param  mixed  $notifiable
 * @return BroadcastMessage
 */
public function toBroadcast($notifiable)
{
    return new BroadcastMessage([
        'invoice_id' => $this->invoice->id,
        'amount' => $this->invoice->amount,
    ]);
}

ブロードキャストキュー設定

すべてのブロードキャスト通知はキューへ投入されます。ブロードキャスト操作に使用されるキューの接続や名前を設定したい場合は、BroadcastMessageのonConnectionとonQueueメソッドを使用してください。

return (new BroadcastMessage($data))
                ->onConnection('sqs')
                ->onQueue('broadcasts');

通知タイプのカスタマイズ

データの指定に付け加え、すべてのブロードキャストは通知の完全なクラス名を含むtypeフィールドを持っています。JavaScriptクライアントへ提供される通知typeをカスタマイズしたい場合は、通知クラスでbroadcastTypeメソッドを定義してください。

use Illuminate\Notifications\Messages\BroadcastMessage;

/**
 * ブロードキャストする通知のタイプ
 *
 * @return string
 */
public function broadcastType()
{
    return 'broadcast.message';
}

通知のリッスン

プライベートチャンネルにブロードキャストされる通知は、{notifiable}.{id}命名規則に従いフォーマットされます。ですから、IDが1のApp\Userインスタンスを通知で送る場合、App.User.1プライベートチャンネルへブロードキャストされます。Laravel Echoを使用していれば、notificationヘルパメソッドを使い、チャンネルへの通知を簡単にリッスンできます。

Echo.private('App.User.' + userId)
    .notification((notification) => {
        console.log(notification.type);
    });

通知チャンネルのカスタマイズ

ブロードキャスト通知のNotifiableエンティティを受け取るチャンネルをカスタマイズしたい場合は、そのエンティティにreceivesBroadcastNotificationsOnメソッドを定義してください。

<?php

namespace App;

use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * ユーザーがブロードキャストされる通知を受け取るチャンネル
     *
     * @return string
     */
    public function receivesBroadcastNotificationsOn()
    {
        return 'users.'.$this->id;
    }
}

SMS通知

事前要件

LaravelのSMS通知送信は、Nexmoを使用します。Nexmoで通知を送る前に、laravel/nexmo-notification-channel Composerパッケージをインストールしてください。

composer require laravel/nexmo-notification-channel

これによりnexmo/laravelパッケージもインストールされます。このパッケージは自身の設定ファイルを持っています。NEXMO_KEYとNEXMO_SECRETの環境変数を使い、Nexmoパブリックキーとシークレットキーを指定できます。

次に、config/services.php設定ファイルへ設定オプションを追加する必要があります。設定例として、以下の設定をコピーして編集してください。

'nexmo' => [
    'sms_from' => '15556666666',
],

sms_fromオプションはSMSメッセージを送る電話番号です。アプリケーションの電話番号は、Nexmoコントロールパネルで作成してください。

SMS通知のフォーマット

SMSとしての通知をサポートするには、通知クラスにtoNexmoメソッドを定義する必要があります。このメソッドは$notifiableエンティティを受け取り、Illuminate\Notifications\Messages\NexmoMessageインスタンスを返す必要があります。

/**
 * 通知のNexmo/SMSプレゼンテーションを取得する
 *
 * @param  mixed  $notifiable
 * @return NexmoMessage
 */
public function toNexmo($notifiable)
{
    return (new NexmoMessage)
                ->content('Your SMS message content');
}

ショートコード通知のフォーマット

Nexmoアカウントで事前に定義したメッセージテンプレートである、ショートコード通知の送信もLaravelはサポートしています。通知のタイプ（alert、2fa、marketingなど）と、そのテンプレートに埋め込むカスタム値を指定します。

/**
 * 通知のNexmo／ショートコードプレゼンテーションを取得する
 *
 * @param  mixed  $notifiable
 * @return array
 */
public function toShortcode($notifiable)
{
    return [
        'type' => 'alert',
        'custom' => [
            'code' => 'ABC123',
        ];
    ];
}

Tip!! SMS通知のルート指定と同様に、通知モデルrouteNotificationForShortcodeメソッドを実装する必要があります。

Unicodeコンテンツ

SMSメッセージにUnicode文字を含む場合は、NexmoMessageインスタンスの生成時に、unicodeメソッドを呼び出してください。

/**
 * 通知のNexmo/SMSプレゼンテーションを取得する
 *
 * @param  mixed  $notifiable
 * @return NexmoMessage
 */
public function toNexmo($notifiable)
{
    return (new NexmoMessage)
                ->content('Your unicode message')
                ->unicode();
}

発信元電話番号のカスタマイズ

config/services.phpファイルで指定した電話番号とは異なる番号から、通知を送りたい場合は、NexmoMessageインスタンスのfromメソッドを使用します。

/**
 * 通知のNexmo/SMSプレゼンテーションを取得する
 *
 * @param  mixed  $notifiable
 * @return NexmoMessage
 */
public function toNexmo($notifiable)
{
    return (new NexmoMessage)
                ->content('Your SMS message content')
                ->from('15554443333');
}

SMS通知のルート指定

特定の電話番号へNexmo通知を送るには、Notifiableエンティティ上でrouteNotificationForNexmoメソッドを定義してください。

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Nexmoチャンネルへの通知をルートする
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return string
     */
    public function routeNotificationForNexmo($notification)
    {
        return $this->phone_number;
    }
}

Slack通知

事前要件

Slackを通して通知を送れるようにするには、ComposerでSlackの通知チャンネルをインストールしてください。

composer require laravel/slack-notification-channel

さらに、Slackチームの"Incoming Webhook"インテグレーションを設定する必要もあります。このインテグレーションは、Slack通知のルートを行う時に使用するURLを提供します。

Slack通知のフォーマット

通知がSlackメッセージとしての送信をサポートする場合、通知クラスにtoSlackメソッドを定義する必要があります。このメソッドは$notifiableエンティティを受け取り、Illuminate\Notifications\Messages\SlackMessageインスタンスを返す必要があります。Slackメッセージはテキストと同時に、追加テキストのフォーマットか、フィールドの配列を「添付」として含みます。基本的なtoSlackの例を見てください。

/**
 * 通知のSlackプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return SlackMessage
 */
public function toSlack($notifiable)
{
    return (new SlackMessage)
                ->content('One of your invoices has been paid!');
}

この例では、Slackへ一行のテキストを送っており、以下のようなメッセージが生成されます。

送信者と受信者のカスタマイズ

fromとtoメソッドを使い、送信者と受信者のカスタマイズができます。fromメソッドはユーザー名と絵文字識別子を受け付け、toメソッドはチャンネルかユーザー名を受け取ります。

/**
 * 通知のSlackプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return SlackMessage
 */
public function toSlack($notifiable)
{
    return (new SlackMessage)
                ->from('Ghost', ':ghost:')
                ->to('#other')
                ->content('This will be sent to #other');
}

絵文字の代わりにロゴイメージを使うこともできます。

/**
 * 通知のSlackプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return SlackMessage
 */
public function toSlack($notifiable)
{
    return (new SlackMessage)
                ->from('Laravel')
                ->image('https://laravel.com/img/favicon/favicon.ico')
                ->content('This will display the Laravel logo next to the message');
}

Slack添付

Slackメッセージに「添付」を追加することもできます。添付はシンプルなテキストメッセージよりも、リッチなフォーマットのオプションを提供します。以下の例では、アプリケーションで起きた例外についてのエラー通知で、例外についての詳細情報を表示するリンクを含めています。

/**
 * 通知のSlackプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return SlackMessage
 */
public function toSlack($notifiable)
{
    $url = url('/exceptions/'.$this->exception->id);

    return (new SlackMessage)
                ->error()
                ->content('Whoops! Something went wrong.')
                ->attachment(function ($attachment) use ($url) {
                    $attachment->title('Exception: File Not Found', $url)
                               ->content('File [background.jpg] was not found.');
                });
}

上の例は、次のようなSlackメッセージを生成します。

添付ではさらに、ユーザーに対し表示すべきデータの配列を指定することもできます。簡単によめるよう指定したデータは、テーブルスタイルの形式で表示されます。

/**
 * 通知のSlackプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return SlackMessage
 */
public function toSlack($notifiable)
{
    $url = url('/invoices/'.$this->invoice->id);

    return (new SlackMessage)
                ->success()
                ->content('One of your invoices has been paid!')
                ->attachment(function ($attachment) use ($url) {
                    $attachment->title('Invoice 1322', $url)
                               ->fields([
                                    'Title' => 'Server Expenses',
                                    'Amount' => '$1,234',
                                    'Via' => 'American Express',
                                    'Was Overdue' => ':-1:',
                                ]);
                });
}

上の例は、以下のようなSlackメッセージを作成します。

Markdown添付コンテンツ

添付フィールドをMarkdownで構成している場合、markdownメソッドでSlackへ指定した添付フィールドがMarkdown形式のテキストであるため、パースしてから表示するように指示します。このメソッドが受け取る値は、pretext、text、fieldsです。Slackの添付形式についての詳細は、Slack APIドキュメントをご覧ください。

/**
 * 通知のSlackプレゼンテーションを取得
 *
 * @param  mixed  $notifiable
 * @return SlackMessage
 */
public function toSlack($notifiable)
{
    $url = url('/exceptions/'.$this->exception->id);

    return (new SlackMessage)
                ->error()
                ->content('Whoops! Something went wrong.')
                ->attachment(function ($attachment) use ($url) {
                    $attachment->title('Exception: File Not Found', $url)
                               ->content('File [background.jpg] was *not found*.')
                               ->markdown(['text']);
                });
}

Slack通知のルート指定

実際の場所へSlack通知をルートするには、通知可能エンティティのrouteNotificationForSlackメソッドを定義します。これは通知が配送されるべきWebhook URLを返す必要があります。Webhook URLは、Slackチームの"Incoming Webhook"サービスを追加することにより、作成されます。

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Slackチャンネルに対する通知をルートする
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return string
     */
    public function routeNotificationForSlack($notification)
    {
        return 'https://hooks.slack.com/services/...';
    }
}

通知のローカライズ

Laravelでは、現在のデフォルト言語とは別のローケルで、通知を送信できます。通知がキュー投入されても、このローケルは保持されます。

希望する言語を指定するために、Illuminate\Notifications\Notificationクラスにlocaleメソッドが用意されています。通知を整形する時点で、アプリケーションはこのローケルへ変更し、フォーマットが完了したら以前のローケルへ戻します。

$user->notify((new InvoicePaid($invoice))->locale('es'));

通知可能な複数のエンティティをローカライズするのも、Notificationファサードにより可能です。

Notification::locale('es')->send($users, new InvoicePaid($invoice));

ユーザー希望のローケル

ユーザーの希望するローケルをアプリケーションで保存しておくことは良くあります。notifiableモデルでHasLocalePreference契約を実装すると、通知送信時にこの保存してあるローケルを使用するように、Laravelへ指示できます。

use Illuminate\Contracts\Translation\HasLocalePreference;

class User extends Model implements HasLocalePreference
{
    /**
     * ユーザーの希望するローケルの取得
     *
     * @return string
     */
    public function preferredLocale()
    {
        return $this->locale;
    }
}

このインターフェイスを実装すると、そのモデルに対しmailableや通知を送信する時に、Laravelは自動的に好みのローケルを使用します。そのため、このインターフェイスを使用する場合、localeメソッドを呼び出す必要はありません。

$user->notify(new InvoicePaid($invoice));

通知イベント

通知が送信されると、Illuminate\Notifications\Events\NotificationSentイベントが、通知システムにより発行されます。これには「通知可能」エンティティと通知インスンタンス自身が含まれます。このイベントのリスナは、EventServiceProviderで登録します。

/**
 * アプリケーションにマップされるイベントリスナ
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Notifications\Events\NotificationSent' => [
        'App\Listeners\LogNotification',
    ],
];

Tip!! EventServiceProviderでリスナを登録した後に、event:generate Artisanコマンドを使うと、リスナクラスが素早く生成できます。

イベントリスナの中で、通知受信者や通知自身について調べるために、そのイベントのnotifiable、notification、channelプロパティにアクセスできます。

/**
 * イベントの処理
 *
 * @param  NotificationSent  $event
 * @return void
 */
public function handle(NotificationSent $event)
{
    // $event->channel
    // $event->notifiable
    // $event->notification
    // $event->response
}

カスタムチャンネル

Laravelはいくつかの通知チャンネルを用意していますが、他のチャンネルを使用し通知を配信するために、独自のドライバーを書くこともあるでしょう。Laravelでは、これも簡単です。手始めに、sendメソッドを含むクラスを定義しましょう。このメソッドは$notifiableと $notificationの、２引数を受け取ります。

<?php

namespace App\Channels;

use Illuminate\Notifications\Notification;

class VoiceChannel
{
    /**
     * 指定された通知の送信
     *
     * @param  mixed  $notifiable
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return void
     */
    public function send($notifiable, Notification $notification)
    {
        $message = $notification->toVoice($notifiable);

        // 通知を$notifiableインスタンスへ送信する…
    }
}

通知チャンネルクラスが定義できたら、通知のviaメソッドから、クラス名を返します。

<?php

namespace App\Notifications;

use App\Channels\Messages\VoiceMessage;
use App\Channels\VoiceChannel;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification
{
    use Queueable;

    /**
     * 通知チャンネルの取得
     *
     * @param  mixed  $notifiable
     * @return array|string
     */
    public function via($notifiable)
    {
        return [VoiceChannel::class];
    }

    /**
     * 通知の音声プレゼンテーションを取得
     *
     * @param  mixed  $notifiable
     * @return VoiceMessage
     */
    public function toVoice($notifiable)
    {
        // ...
    }
}