NewWe open-sourced 50+ Laravel packages
Custom AI apps, agents and automation — Roundly ConsultingRoundly
All packages

Require the package, publish its migrations and options-for-laravel’s (preferences are stored through it), and migrate. The service provider is auto-discovered together with the providers of the Roundly packages it builds on — crypto, enums, options and package-toolkit:

composer require roundly-consulting/notifications-for-laravel
php artisan vendor:publish --tag="notifications-migrations"
php artisan vendor:publish --tag="options-migrations"     # preferences are stored through options-for-laravel
php artisan migrate

The migrations are publish-only — the provider loads none of them. Five tables are created, in this order: notification_reminders, notification_inbox_items, notification_digest_runs, notification_deliveries and notification_receipts. Every instant column is a dateTime and every value is UTC, so there is no MySQL 2038 limit and no DST-ambiguous wall-clock value. Laravel’s own notifications table is never touched.

Or let the install command do the publishing:

# Publishes the config and the migrations (refusing when a configured table already exists)
# and prints the schedule lines and trait snippets
php artisan notifications:install

1. Schedule the sweep

Held mail, trailing mail, retries, digests, reminders and escalations all go out from one command. Schedule it every minute — nothing is auto-scheduled by the package:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('notifications:sweep')->everyMinute()->withoutOverlapping(10)->onOneServer();
Schedule::command('notifications:prune')->daily();

withoutOverlapping(10) matters: the default mutex lives 24 hours, so a killed sweep would otherwise stall held mail, digests and reminders for a day. Each sweep step claims its rows by compare-and-set, so two schedulers never send one row twice; onOneServer() just saves work. Run a queue worker too — mail, digests and large fan-outs are queued unless notifications.queue.enabled is off.

2. Settle the key types before migrating

With bigint ids everywhere the defaults fit. With UUID or ULID keys, set them before php artisan migrate:

# Before php artisan migrate — the values are frozen once the tables exist
NOTIFICATIONS_KEY_TYPE=uuid            # recipients and actors — must equal options.key_type
NOTIFICATIONS_SUBJECT_KEY_TYPE=        # blank = key_type
NOTIFICATIONS_CONTEXT_KEY_TYPE=        # blank = key_type
NOTIFICATIONS_PRIMARY_KEY_TYPE=bigint  # the package tables' own ids (bigint, uuid or ulid)

notifications.key_type must equal your user key type and options.key_type. Before any write each morph value is checked against its key type, and a mismatch throws InvalidNotificationsConfigurationException naming the config key and the model basename — never a raw SQL error.

3. Make your User a recipient

A recipient is an Eloquent model that can be mailed (Laravel’s Notifiable or RoutesNotifications, or notifications.mail.address_resolver), is Authenticatable when a type relies on the default Gate access check, and uses ReceivesNotifications:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use RoundlyConsulting\Notifications\Traits\ReceivesNotifications;

class User extends Authenticatable
{
    use Notifiable;              // mail routing (Laravel)
    use ReceivesNotifications;   // inbox(), notificationPreferences(), unreadNotificationCount()
}

ReceivesNotifications is named so it composes with Notifiable: no notifications(), notify() or unreadNotifications() clash. Without a mail address a delivery becomes undeliverable — never a fatal error at delivery.

4. Describe a type and send it

A type needs a view policy on its subject (here PurchaseRequest), a group that lists its members (Company implementing ProvidesNotificationRecipients) and a recipient as above:

use Illuminate\Database\Eloquent\Model;
use RoundlyConsulting\Notifications\NotificationPayload;
use RoundlyConsulting\Notifications\NotificationType;

// app/Notifications/Types/RequestAwaitingApproval.php — listed in config('notifications.types')
final class RequestAwaitingApproval extends NotificationType
{
    public function key(): string { return 'request.awaiting_approval'; }
    public function category(): string { return 'requests'; }
    public function subject(): ?string { return PurchaseRequest::class; }   // access check: Gate "view" on it
    public function window(): ?string { return 'PT5M'; }                    // 10 events in 5 min → 1 item, 1 mail

    public function title(NotificationPayload $p): string
    {
        return __('app.notifications.awaiting', ['ref' => $p->data['reference'], 'count' => $p->count]);
    }

    public function url(NotificationPayload $p): ?string { return route('requests.show', $p->subjectKey); }
    public function context(?Model $subject): ?Model { return $subject?->company; }   // "Acme s.r.o." label
}

Then send it from a feature — inbox, mail, preferences, de-dup, quiet hours and access are applied for you — and read the user’s inbox:

use RoundlyConsulting\Notifications\Facades\Notifications;
use RoundlyConsulting\Notifications\Recipients;

Notifications::send(
    'request.awaiting_approval',
    $request,
    Recipients::role($request->company, 'approver'),
    ['reference' => $request->reference],
    actor: $request->author,
);

$items = Notifications::inbox($user)->unread()->paginate();   // InboxItemResource::collection($items)
Notifications::inbox($user)->unreadCount();                   // 3
Notifications::inbox($user)->markAllRead();

Publish tags

TagPublishes
notifications-migrationsSeven migrations — reminders, inbox items, digest runs, deliveries, receipts, then the reminders’ recipient morph (1.3.0) and snoozed_until (1.4.0) — timestamped on publish. Required: the provider loads none of them.
options-migrationsoptions-for-laravel’s table — preferences are stored through it. Required.
notifications-configconfig/notifications.php
notifications-translationslang/vendor/notifications/{en,sk}/{mail,digest,enums,exceptions,preferences,unsubscribe}.php
notifications-viewsThe digest mail’s markdown view notifications::mail.digest and the unsubscribe page notifications::unsubscribe.
notifications-routesroutes/notifications.php and routes/unsubscribe.php — once published they load instead of the package’s files, still behind notifications.routes.enabled and notifications.mail.list_unsubscribe.enabled.
php artisan vendor:publish --tag="notifications-config"         # config/notifications.php
php artisan vendor:publish --tag="notifications-translations"   # lang/vendor/notifications/{en,sk}/…
php artisan vendor:publish --tag="notifications-views"          # the digest mail and unsubscribe page views
php artisan vendor:publish --tag="notifications-routes"         # routes/notifications.php + routes/unsubscribe.php — replace the package's files

Tables

TableHolds
notification_inbox_itemsRecipient, subject, context and actor morphs, count, data, a title and url snapshot, a unique open_key, collapse_until, reminder_id, read and archived timestamps.
notification_deliveriesStatus, a unique open_key, window_ends_at, send_after, events_count, digest frequency / period / run, the encrypted interop payload (hidden), notification_id, source.
notification_remindersKind, type, rule, subject morph, anchor + offset + anchor_value, due_at, level, parent_id, stored recipients and data, a unique active_key, acknowledgement + acknowledger morph, since 1.3.0 the recipient morph (nullable) of a repeating chain, and since 1.4.0 snoozed_until.
notification_digest_runsUnique per recipient, frequency and period.
notification_receiptsUnique per key and recipient; no soft deletes — a ledger.

Translations and labels

notifications::mail, notifications::digest, notifications::enums, notifications::exceptions and notifications::preferences ship in English and Slovak. The labels of your types and categories live in your own translations:

// lang/en/notifications.php — your type and category labels (and lang/sk/notifications.php)
return [
    'types' => [
        'request.awaiting_approval' => [
            'label' => 'Request awaiting approval',
            'description' => 'When a purchase request needs your approval.',
        ],
    ],
    'categories' => [
        'requests' => 'Requests',
    ],
];

Check the setup

php artisan notifications:doctor
php artisan about --only=notifications

The doctor reports key-type drift, a sync queue, a non-shared preference lock store, unsubscribe links that are not https, a non-shared rate-limit store, invalid default quiet hours, types without a policy or ability, interop map problems and a user model that cannot be mailed (see Commands). The about section shows the type count, the queue (connection and queue only as SET or DEFAULT), routes, List-Unsubscribe (ON or OFF), the mail rate limit (OFF, or ON with defer or skip), the four key types (key, subject, primary and context), the digest default and the interop counts — never a secret.

Upgrading to 1.4

1.4.0 adds per-recipient control of repeating reminders (see Reminders and escalation). Publish and run the new migration 0007 — it adds a nullable snoozed_until column to notification_reminders, is additive and only snooze() needs it:

php artisan vendor:publish --tag="notifications-migrations"   # adds 0007 — snoozed_until on notification_reminders
php artisan migrate

One behaviour change: HasNotificationReminders now also syncs on save when only a repeating rule’s from() attribute changed, so publishing a draft later starts the chains of a rule with ->to(), and a republish re-arms chains that had all ended.

Upgrading from 1.2

1.3.0 adds repeating reminders. Publish and run the new migration — it adds a nullable recipient morph (following notifications.key_type) to notification_reminders, is additive and leaves existing reminders unchanged:

php artisan vendor:publish --tag="notifications-migrations"   # adds 0006_add_recipient_to_notification_reminders_table
php artisan migrate
  • acknowledge(by: $user) ends only $user’s repeating chain. One-off reminders and send escalations are acknowledged subject-wide as before.
  • Reminder and escalation sends now go through the manager, so Notifications::fake() records them like any other send. Production delivery is unchanged.

Upgrading from 1.1

No migration and no required config change. The three new mail features change nothing until you opt in: one-click unsubscribe and the rate limit are off, and the default NullSuppressionList suppresses nothing (see Email). The unsubscribe route lives in its own routes/unsubscribe.php, so a routes/notifications.php you published earlier needs no edit:

# Opt in to the new mail features (all three are off or no-op by default)
NOTIFICATIONS_LIST_UNSUBSCRIBE=on   # List-Unsubscribe headers + the one-click route
NOTIFICATIONS_MAIL_RATE_LIMIT=on    # per-recipient (and optionally per-context) caps
# mail.suppression_list → your SuppressionList class (default NullSuppressionList)
  • Muting the inbox of a whole category while notifications.preferences.inbox_mutable is off now throws LockedNotificationChannelException (422) — through muteCategory($category, Channel::Inbox), a PreferencesUpdate and PATCH /preferences under categories.<category>.inbox — like the same mute of one type. It used to store an override that was then ignored.
  • An escalation level’s own type: must be registered and take the escalated subject: ->escalate(type: …) throws InvalidReminderRuleException at the call, and a type rule’s escalation is checked once the app has booted. Such a level used to be accepted and die at fire time, escalating nobody.
  • Inbox items of escalations and reminders keep the escalation level and the reminder reference under data._notifications. The API and publicData() never see it, but code reading $item->data raw now finds that key on those items.
  • A preference write that cannot get the user’s lock in time throws PreferencesLockedException (423, preferences_locked) instead of Laravel’s LockTimeoutException — PATCH /preferences answers 423 instead of 500.
  • Under Notifications::fake(), send(Foo::class, …) returns a SendResult whose type is the key, and every type-taking assertion accepts a key or a class (see Testing).

Upgrading from 1.0

No migration and no config change. Two things may need a hand: a published routes file does not get the new DELETE /inbox/{item} endpoint by itself, and code that built the manager or the fake with new and a container must drop the argument:

// routes/notifications.php — only if you published it: the copy replaces the package's file
Route::delete('inbox/{item}', [InboxController::class, 'destroy'])->name('inbox.destroy');
// The manager and the fake take no constructor arguments — they resolve the current container
$manager = app(NotificationsManager::class);   // not new NotificationsManager($container)
$fake = Notifications::fake();
  • Switching off a channel that cannot be switched off now throws LockedNotificationChannelException (422) — PATCH /preferences answers 422 under channels.<type>.<channel> where it used to answer 200 (see Preferences).
  • A subject has one open send-level escalation chain per type: repeated sends with ->escalate() join the open chain instead of arming one each (see Reminders and escalation).
  • Under Notifications::fake(), a send the real pipeline refuses up front now throws the same exception instead of being recorded (see Testing).
  • InboxItemResource renders data as [] for an item whose type is no longer registered, and muted() is false for a type that sends no mail.

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.