Writing notifications
Last updated:
On this page
A notification extends Javaabu\Notifications\BaseNotification and says what it has to say once, in message(). The package builds every channel's format from it.
namespace App\Notifications;
use App\Models\Order;
use Illuminate\Contracts\Queue\ShouldQueue;
use Javaabu\Notifications\BaseNotification;
use Javaabu\Notifications\Messages\NotificationMessage;
class OrderShippedNotification extends BaseNotification implements ShouldQueue
{
protected array $channels = ['database', 'mail', 'sms', 'fcm'];
protected ?string $icon = 'send';
protected ?string $color = 'success';
public function __construct(
public Order $order,
) {}
public static function label(): string
{
return __('Order shipped');
}
public function message(object $notifiable): NotificationMessage
{
return NotificationMessage::make(__('Your order has shipped'))
->line(__('Order :number is on its way.', ['number' => $this->order->number]))
->line(__('It should reach you in 2 days.'))
->action(__('Track order'), route('orders.show', $this->order))
->subject($this->order)
->data(['order_id' => $this->order->id]);
}
}
Send it the Laravel way:
$user->notify(new OrderShippedNotification($order));
Notification::send($users, new OrderShippedNotification($order));
Notification::route('mail', 'customer@example.com')->notify(new OrderShippedNotification($order));
Implement ShouldQueue to send it from the queue, as with any Laravel notification. BaseNotification already uses Queueable.
The message
NotificationMessage::make($title) starts a message. Every method returns the message.
| Method | Used for |
|---|---|
title(string) |
The mail subject, the title in the bell and on the page, the push title, the first line of the SMS |
line(?string) |
Adds a paragraph to the body. Empty lines are skipped. |
lines(array) |
Adds several paragraphs |
body(?string) |
Replaces the body with one paragraph |
action(string $text, string $url) |
The mail button, and where opening the notification goes |
url(?string) |
Where opening the notification goes, without a mail button |
icon(?string) |
The icon in the bell and on the page (see Icons) |
color(?string) |
primary, secondary, success, info, warning, danger or neutral |
thumbnail(?string) |
An image URL shown instead of the icon, and in push notifications |
subject(?Model) |
The model the notification is about (see Database notifications) |
level(string), success(), error() |
The mail button colour. success() and error() also set the colour to success / danger unless you set one. |
greeting(?string), salutation(?string) |
The mail's first and last lines (the defaults are "Hello!" and "Regards," with your app's name) |
data(array) |
Extra data kept with database notifications and sent with push notifications |
sms(?string) |
The SMS text, instead of the title, body and URL |
mail(?Closure) |
Change the MailMessage: fn (MailMessage $mail) => $mail->cc('…')->attach('…') |
fcm(?Closure) |
Change the FcmMessage: fn (FcmMessage $message) => $message->custom([...]) |
message() receives the notifiable, so a message can depend on who reads it:
public function message(object $notifiable): NotificationMessage
{
return NotificationMessage::make(__('New comment on :title', ['title' => $this->post->title]))
->body($this->comment->body)
->url(route('posts.show', $this->post) . '#comment-' . $this->comment->id)
->greeting(__('Hello :name,', ['name' => $notifiable->name]));
}
What each channel gets
| Channel | Built by | What's sent |
|---|---|---|
mail |
toMail() |
A branded MailMessage: the title as subject, the lines, the action button, the greeting and salutation |
database |
toDatabase() |
The title, body, action, icon, colour, thumbnail, level and data, and the subject in its own columns |
broadcast |
toBroadcast() |
The title, body, icon and colour, as the notification.created type. Added by itself when live updates are on. |
sms |
toSms() |
sms(), or the title, body and URL separated by blank lines |
fcm |
toFcm() |
A push notification with the title, body and thumbnail, and the id, type, URL and data as string data |
Any of them can still be overridden the Laravel way, for a channel that needs something the message can't say:
public function toMail(object $notifiable): MailMessage
{
return parent::toMail($notifiable)->attach(storage_path("invoices/{$this->order->id}.pdf"));
}
toArray() returns the same as the database payload without the per-language texts, so Notification::fake() assertions and custom channels can use it.
Icons and colours for a type
Set $icon and $color on the class for every notification of that type; the message's own icon() and color() win over them. Without either, notifications.defaults is used (bell, primary).
A label for the type
label() names the type on the notifications page's filter, and anywhere you list notification types, for example a preferences page. By default it's the class name without "Notification", as words: OrderShippedNotification → "Order shipped". Override it to translate it:
public static function label(): string
{
return __('Order shipped');
}
Languages
Each notifiable is notified in its own language. message() runs inside that locale, so __() returns the notifiable's language, and the mail layout's own words (greeting, salutation, footer) and its direction follow it.
The locale comes from:
- Laravel's
HasLocalePreference:preferredLocale()on the notifiable. - Otherwise, the attribute in
notifications.locale_attribute(localeby default), when the model has it. - Otherwise, the app's current locale.
class User extends Authenticatable implements HasLocalePreference
{
public function preferredLocale(): string
{
return $this->language ?? 'dv';
}
}
With javaabu/translatable installed, only its active languages count, and database notifications are stored in all of them.