Skip to content

Notifications

David Ciulla edited this page Nov 7, 2026 · 2 revisions

Notifications

Laravex's notification system allows you to send notifications across a variety of delivery channels from a single, expressive API. Notifications are sent through Laravex.Notifications.Notifier and can be received by any notifiable model.


Supported Channels

Channel atom Delivery
:mail Sends a mail message via Laravex.Mail.Mailer
:database Writes to the notifications table (and a JSON fallback file)
:log Logs the notification payload via Laravex.Log.Logger.info/2
:broadcast Broadcasts the payload via Laravex.Broadcasting.Broadcaster

Any other channel atom raises ArgumentError at delivery time.


Creating a Notification

./artisan make:notification InvoicePaid

A notification module typically implements via/1 and one or more to_{channel}/1 callbacks:

defmodule App.Notifications.InvoicePaid do
  def via(_notifiable), do: [:mail, :database]

  def to_mail(notifiable) do
    %{
      to:      notifiable.email,
      subject: "Invoice Paid",
      body:    "Your invoice has been paid. Thank you!"
    }
  end

  def to_database(notifiable) do
    %{
      "invoice_id" => notifiable.invoice_id,
      "amount"     => notifiable.amount
    }
  end
end

If via/1 is not defined, the system defaults to [:mail].


Sending Notifications

Via the Notifier

Laravex.Notifications.Notifier.send(user, App.Notifications.InvoicePaid)

# With a payload (passed as the second element of a tuple)
Laravex.Notifications.Notifier.send(user, {App.Notifications.InvoicePaid, %{amount: 99.0}})

Via the Notifiable Model

Add the Laravex.Notifications.Notifiable behaviour to any model:

defmodule App.Models.User do
  use Laravex.Eloquex.Model
  use Laravex.Notifications.Notifiable

  # Notifiable injects: notify/2, notifications/1, unread_notifications/1,
  #                     mark_notification_as_read/2, mark_notifications_as_read/1
end
user.notify(App.Notifications.InvoicePaid)
user.notify({App.Notifications.InvoicePaid, %{amount: 99.0}})

Channel Routing

Mail

The :mail channel calls notification.to_mail(notifiable) (or to_mail(notifiable, payload) for tuple sends) and passes the result to Laravex.Mail.Mailer.send/1.

The recipient address is resolved by:

  1. Calling notifiable.__struct__.route_notification_for_mail(notifiable) if defined
  2. Falling back to notifiable.email

The Notifiable macro injects a default route_notification_for_mail/1 that reads notifiable.email.

Database

The :database channel stores notifications in two places:

  1. notifications table — if the table exists (created by the included migration).
  2. storage/app/notifications/*.json — a JSON file fallback always written, regardless of the table.

The stored payload comes from notification.to_database(notifiable) or notification.to_array(notifiable). If neither is defined, a default map of %{"notification" => ModuleName, "payload" => payload} is stored.

./artisan migrate   # creates the notifications table

Log

The :log channel writes a structured log entry with the notification module, the recipient address, and the payload.

Broadcast

The :broadcast channel broadcasts the payload via Laravex.Broadcasting.Broadcaster.event/3.

  • Channel name: resolved from notification.broadcast_on(notifiable) → notification.broadcast_on() → "App.Models.User.{id}"
  • Event name: resolved from notification.broadcast_as() → the last part of the module name
  • Payload: from notification.to_array(notifiable) or notification.to_database(notifiable)

Notification Inbox (Database Channel)

When using the :database channel and the Notifiable module, models gain inbox helpers:

# All notifications (most recent first)
user.notifications()

# Unread notifications only (read_at IS NULL)
user.unread_notifications()

# Mark a single notification as read
user.mark_notification_as_read(notification_id)

# Mark all notifications as read
user.mark_notifications_as_read()

The notifications table schema (from the included migration) has these columns:

Column Type Description
id UUID Notification UUID
type string Notification module name
notifiable_type string Notifiable model module name
notifiable_id integer Notifiable model ID
data JSON Serialised notification payload
read_at datetime Null until read
created_at datetime
updated_at datetime

Testing

Laravex.Notifications.Notifier.fake()

user.notify(App.Notifications.InvoicePaid)

# Returns true if any recorded notification matches the predicate
Laravex.Notifications.Notifier.assert_sent(fn n ->
  n.notification == App.Notifications.InvoicePaid
end)

Laravex.Notifications.Notifier.assert_sent(fn n ->
  n.notifiable.id == user.id
end)

# Inspect all sent notifications
Laravex.Notifications.Notifier.sent()
# => [%{notifiable: %User{…}, notification: App.Notifications.InvoicePaid, payload: nil}]

Deferred Notifications

Send a notification after a delay (queued via the job queue):

# Notify after 15 minutes (delay in seconds)
Laravex.Notifications.Channel.later(user, App.Notifications.WelcomeEmail, %{}, delay: 900)

# notify_later/4 alias — same behaviour
Laravex.Notifications.Channel.notify_later(user, App.Notifications.OrderShipped, %{order: order}, delay: 60)

The underlying job is enqueued via the queue worker and processed asynchronously.


See Also

Clone this wiki locally