Repository navigation
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.
| 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.
./artisan make:notification InvoicePaidA 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
endIf via/1 is not defined, the system defaults to [:mail].
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}})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
enduser.notify(App.Notifications.InvoicePaid)
user.notify({App.Notifications.InvoicePaid, %{amount: 99.0}})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:
- Calling
notifiable.__struct__.route_notification_for_mail(notifiable)if defined - Falling back to
notifiable.email
The Notifiable macro injects a default route_notification_for_mail/1 that reads notifiable.email.
The :database channel stores notifications in two places:
-
notificationstable — if the table exists (created by the included migration). -
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 tableThe :log channel writes a structured log entry with the notification module, the recipient address, and the payload.
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)ornotification.to_database(notifiable)
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 |
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}]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.
-
Mail —
:mailchannel delivery -
Broadcasting —
:broadcastchannel delivery -
Artisan-Console —
make:notification -
Database —
notificationstable migration
Laravex — Laravel-faithful application skeleton & runtime for Elixir.
GitHub
·
Docs
·
Limitations
·
Laravel Docs
Not affiliated with Laravel LLC or the Elixir core team. Built to feel like Laravel on the BEAM.
- Home
- Installation
- Configuration
- Directory-Structure
- Request-Lifecycle
- Service-Container
- Service-Providers
- Deployment
- Routing
- Middleware
- CSRF-Protection
- Controllers
- Requests
- Responses
- Views
- Blade-Templates
- Asset-Bundling
- Session
- Validation
- Error-Handling
- Logging
- Artisan-Console
- Broadcasting
- Cache
- Collections
- Events
- File-Storage
- Helpers
- HTTP-Client
- Localization
- Notifications
- Pipeline
- Queues
- Rate-Limiting
- Strings
- Task-Scheduling