イントロダクション
メール送信に加え、LaravelはSMS(以前、Nexmoとして知られていたVonageを使用)、Slackなどの、さまざまな複数チャンネルへ渡る通知をサポートしています。通知はWebインターフェイスで表示できるように、データベースに保存することもできます。
通常、通知はアプリケーションで何かが起きたことをユーザーへ知らせる、短い情報メッセージです。たとえば、課金アプリを作成しているなら、メールとSMSチャンネルで「課金支払い」を送信できます。
通知の作成
Laravelの各通知は、(通常、app/Notifications
ディレクトリに設置される)クラスにより表されます。このディレクトリがアプリケーションで見つからなくても、心配ありません。make:notification
Artisanコマンドを実行すると、作成されます。
php artisan make:notification InvoicePaid
このコマンドにより、真新しい通知クラスが、app/Notifications
ディレクトリに生成されます。各通知クラスはvia
メソッドと、特定のチャンネルに最適化したメッセージへ変換する、いくつかのメッセージ構築メソッド(toMail
、toDatabase
など)を含んでいます。
通知の送信
Notifiableトレイトの使用
通知は2つの方法で送信されます。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
メソッドで指定する配列の第2要素としてビュー名を渡すことにより、メールメッセージの平文テキストビューを指定できます。
/**
* 通知のメールプレゼンテーションを取得
*
* @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 | テーブル | 例 |
| ------------- |:-------------:| --------:|
| 第2カラムは | 中央寄せ | $10 |
| 第3カラムは | 右寄せ | $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
の、2引数を受け取ります。
<?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)
{
// ...
}
}