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

Reminders and escalation

Reminder rules belong to a type with a subject() and are relative to a date attribute of it:

use RoundlyConsulting\Notifications\Recipients;
use RoundlyConsulting\Notifications\Reminders\Reminder;

final class ContractExpiring extends NotificationType
{
    public function key(): string { return 'contract.expiring'; }
    public function category(): string { return 'contracts'; }
    public function subject(): ?string { return Contract::class; }

    public function reminders(): array
    {
        return [
            Reminder::before('expires_at', 'P60D', 'P30D', 'P7D')
                ->to(Recipients::owner())
                ->while(fn (Contract $contract): bool => $contract->terminated_at === null)
                ->escalate(after: 'P3D', to: fn (Contract $contract) => Recipients::role($contract->company, 'manager')),
        ];
    }

    public function title(NotificationPayload $p): string
    {
        return __('app.contract_expiring', ['offset' => $p->data['reminder'] ?? '']);   // '-P30D'
    }
}
BuilderMeaning
Reminder::before($attribute, ...$offsets) / after(...)Anchor ∓ offset (ISO-8601 or relative), 1–25 positive offsets.
Reminder::at(CarbonInterface $when)Absolute — ad-hoc schedules only.
->key('expiry')A stable rule key (default {attribute}:{direction}); two rules on one attribute and direction need distinct keys.
->to($recipients)Who is reminded; a rule without to() is a template for schedule($type, to: …).
->while(fn (Model $subject): bool)Checked at fire time with the fresh subject; false cancels (condition).
->escalate(after:, to:, type: null)Repeatable — a chain of levels. An unreadable or non-positive delay throws at once; so does a level type: that is not registered or does not take the subject.
->acknowledgedOnRead()Reading the reminder’s inbox item acknowledges it.
->rearm(false)Do not re-arm sent reminders when the anchor moves later (default: re-arm).
Reminder::every($interval)A repeating rule (since 1.3.0), with from(), startingAfter(), times() and until() — see Repeating reminders.
Reminder::after('signed_at', 'P1Y')
    ->key('anniversary')                         // two rules on one attribute and direction need distinct keys
    ->to(Recipients::owner())
    ->acknowledgedOnRead()                       // reading the item acknowledges it
    ->rearm(false);                              // don't re-arm sent reminders when the anchor moves later

Reminder::before('deadline', 'PT1H');            // a template rule without to(): schedule() supplies recipients

Rules are validated at registration: the type has a subject, the attribute is not empty, 1–25 positive offsets, rule keys unique per type, no at() in a type rule. The anchor is read through your cast and converted to UTC. Time offsets (PT…) are absolute; calendar offsets (P…D/W/M/Y) are applied on the anchor’s wall clock in app.timezone, so “7 days before 09:00” stays 09:00 local across a DST change. Months and years never overflow: they clamp to the last day of the target month (P1M before 31 March is 28 February, P1Y after 29 February is 28 February), then the days apply (P1M1D before 31 March is 27 February).

Following the date

With the HasNotificationReminders trait on the subject (see Recipient and subject models), every save syncs. Per rule and offset:

  • Anchor cleared → pending rows cancelled (anchor_cleared).
  • A pending row whose due time moved → re-timed (ReminderRescheduled), or cancelled (passed) when the new time is already past — moving the anchor earlier never fires the skipped offsets all at once. A passed row never ran for its date, so moving the date back schedules it again.
  • No pending row → scheduled when the due time is in the future, unless a row for that very anchor already finished; a sent row of an older anchor re-arms (a renewal). Past offsets are never back-filled.
  • A unique key makes two concurrent syncs schedule one row; a conflict never throws.
  • A query-builder update bypasses model events: the fire step re-reads the anchor, so a stale due time reschedules itself instead of firing.

The explicit API and ad-hoc reminders

Notifications::for($contract)->reminders()->sync();                      // ?string $type
Notifications::for($contract)->reminders()->schedule('task.due', to: $assignee);   // template rules, stored recipients
Notifications::for($contract)->reminders()->cancel();                    // ?string $type
Notifications::for($policy)->reminders()->schedule('policy.unacknowledged', to: $user, restart: true);       // since 1.4.0
Notifications::for($policy)->reminders()->cancel('policy.unacknowledged', for: $user);                       // one recipient's chains (1.4.0)
Notifications::for($policy)->reminders()->snooze('policy.unacknowledged', $user, until: now()->addWeek());   // 1.4.0
Notifications::for($contract)->reminders()->pending();                   // Collection<NotificationReminder>
Notifications::for($contract)->reminders()->all();

// Ad-hoc reminders
Notifications::for($task)->remind('task.due', Reminder::before('deadline', 'PT1H'), to: $task->assignee);
Notifications::for($report)->remind('report.ready', Reminder::at(now()->addDay()), to: $user, data: ['id' => 7]);
Notifications::for($task)->remind('task.due', Reminder::before('deadline', 'P1D', 'PT1H')->key('deadline'), to: $task->assignee);   // one row per offset

Notifications::reminders()->backfill('contract.expiring');               // every subject of the type's class (chunks of 200)
Notifications::reminders()->fireDue();                                   // FiredReminders — what the sweep runs

Ad-hoc reminders store their recipients and data; an anchored one follows its anchor like a rule reminder, and offsets already in the past are skipped — remind() returns only the rows it scheduled, [] when every offset has passed; an at() instant is scheduled as given. A second remind() with the same key (->key(), else the attribute + offset, or the instant) replaces the pending row; with ->key() and several offsets each offset keeps its own row under that key, and a repeat replaces each one. A remind() or schedule() that lands while the same reminder is firing waits as one extra row, replaced by later calls and given the key once the fire closes — never a second copy that fires twice. A type without a subject() takes ad-hoc reminders on any model (report.ready above): the reminder fires about no subject — the model only anchors and owns it, and deleting it cancels the reminder — and an anchored one follows its anchor on save when the model uses HasNotificationReminders. remind() refuses a subject of another class than the type’s subject() (InvalidNotificationSubjectException). Ad-hoc reminders take no condition, escalation or acknowledgedOnRead() — a rule carrying one throws InvalidReminderRuleException; declare a rule on the type for those. Recipients must be storable (no closures). For subjects that existed before a type was added, run notifications:reminders:sync — backfill() syncs in chunks of 200 and throws InvalidReminderRuleException for a type without a subject class or reminder rules.

Repeating reminders

Since 1.3.0. “Remind everyone who hasn’t acknowledged the policy every 7 days” is a type rule built with Reminder::every():

use RoundlyConsulting\Notifications\Recipients;
use RoundlyConsulting\Notifications\Reminders\Reminder;

public function reminders(): array
{
    return [
        Reminder::every('7 days')                 // CarbonInterval, ISO-8601 or relative
            ->from('published_at')                // anchor; default: when the chain was scheduled
            ->startingAfter('7 days')             // first one after the anchor; default: one interval; 'PT0S' = at once
            ->times(5)                            // optional: at most 5 per recipient
            ->until(fn (Policy $policy) => $policy->deadline_at)   // optional: CarbonInterface or closure (null = no end)
            ->while(fn (Policy $policy): bool => $policy->is_active)
            ->acknowledgedOnRead()
            ->escalate(3, to: fn (Policy $policy) => Recipients::role($policy->company, 'compliance')),
    ];
}

Notifications::for($policy)->reminders()->schedule('policy.unacknowledged', to: $employees);
Notifications::for($policy)->acknowledge('policy.unacknowledged', by: $employee);   // ends $employee's chain only
  • One chain per recipient. Each recipient gets their own chain of rows (the recipient morph on the row); only one row of a chain is open at a time, and firing it writes the next one (level = the reminder’s number), so fireDue() stays a plain due-time query. The rule key is {attribute}:every, or scheduled:every without from(); two repeating rules on one anchor need ->key().
  • Slots count from the anchor: anchor + first delay + n × interval, calendar-aware like offsets (09:00 local stays 09:00 across DST). A late sweep never drifts the chain or sends a burst — a reminder more than reminders.max_lateness overdue is skipped (late) and the chain continues at the next slot ahead.
  • A chain ends when its recipient acknowledges, while() turns false (condition), the subject’s reminders are cancelled (cancel() or deletion), the recipient’s are (cancel(for:), since 1.4.0), the anchor is cleared (anchor_cleared), times() is reached, or the next slot falls after until(). An acknowledgement that lands while a reminder is being sent ends the chain after it.
  • Scheduling again only adds newcomers: schedule() — or sync() for a rule with ->to() — starts a chain for every recipient without one. A running chain is left alone, and one that already ran for the current anchor (acknowledged, ended, cancelled) is not restarted — unless you pass restart: true (see below). A late joiner starts at the chain’s next slot ahead — aligned to the anchor with from(), to their own scheduling time without it. A chain anchored to scheduling runs once per recipient.
  • When the anchor changes (sync(), the trait’s save hook, or at fire time), the open row re-times to the new anchor’s first slot still ahead. When it moves later — a republished policy — ended chains start over at level 1; ->rearm(false) turns that off. Since 1.4.0 the trait’s save hook also reacts when the only changed attribute is a repeating rule’s from() — so a draft published later starts the chains of a rule with ->to(), and a republish re-arms chains that had all ended.
  • Escalation arms each level once per chain: escalate('P10D', …) counts from the chain’s first reminder, escalate(3, …) — an int, repeating rules only — arms after the 3rd reminder went out unacknowledged, due one interval later. The escalation row carries the chain’s recipient, so their acknowledgement cancels it and another recipient’s does not.
  • Each firing works like a one-off reminder: idempotency key reminder:{id}, quiet hours, digests, preferences and access all apply. Its data is ['reminder' => 'P7D', 'occurrence' => n].
  • A repeating rule is a type rule — remind() refuses one. from(), startingAfter(), times(), until() and escalate(int) on a one-off rule, an unreadable or non-positive interval, a negative first delay or times(0) throw InvalidReminderRuleException (invalid_repeat) where written.

Controlling one recipient’s chain

Since 1.4.0. All three go through the manager — so Notifications::fake() records them — are idempotent and audit through the existing events:

$reminders = Notifications::for($policy)->reminders();

// Start again after a chain ended for this anchor — e.g. acknowledgement switched off (while() false) and on again.
$reminders->schedule('policy.unacknowledged', to: $employees, restart: true);

// Stop one person's reminders (and the escalations their chain armed); everyone else keeps theirs.
$reminders->cancel('policy.unacknowledged', for: $employee);

// A manual "remind now" — then push their next automatic one a full interval out.
Notifications::for($policy)->send('policy.unacknowledged', $employee);
$reminders->snooze('policy.unacknowledged', $employee, until: now()->addDays(7));
  • schedule(…, restart: true) starts a fresh chain for every listed recipient whose chain ended — acknowledged, while() false, cancelled, times() / until() reached — even for the same anchor. The new chain counts from reminder #1 (level 1, a fresh times() budget, escalations armed anew) and starts at the anchor’s next slot ahead, never a slot the ended chain already sent. An open chain is kept, so a repeat call changes nothing. while() is not checked here: if it is still false, the chain ends again at its first fire. Plain schedule() and sync() keep their 1.3 behaviour — nothing restarts implicitly.
  • cancel($type = null, for: $recipient) cancels only that recipient’s pending chain rows and the escalations their chain armed (ReminderCancelled, cancel_reason cancelled); without a type, across every type of the subject. One-off reminders are shared by their recipients and are left alone. It returns the rows cancelled — 0 for a recipient without an open chain, or on a second call. A later sync() or plain schedule() does not bring the chain back for the same anchor; restart: true does, and so does an anchor that moves later.
  • snooze($type, $recipient, until: $instant) moves that recipient’s open reminder of each repeating rule of the type to $until; later reminders follow whole intervals after it ($until + n × interval, calendar-aware), while other recipients keep the original slots. It returns the chains changed and dispatches ReminderRescheduled. The row keeps its level, so times() still counts every reminder and escalate(n) still arms after the n-th one; escalations already armed are not moved. The snooze is stored on the row (snoozed_until, NotificationReminder::isSnoozed()) and carried to every later row of the chain.

Snooze rules: a recipient without an open chain is left alone (0) — a snooze never starts a chain, use restart: true; snoozing to the instant already set is 0 too. An $until after the rule’s until() ends the chain (passed). When the anchor moves, the open row re-times to the new anchor’s slots and the snooze is dropped — a new publication is a new cadence. A reminder being sent at that very moment is not snoozed. $until not in the future, or a type without a repeating rule, is refused up front — under the fake too — with InvalidReminderRuleException (invalid_snooze, 422); an unknown type throws UnknownNotificationTypeException. Snooze needs the 1.4.0 migration (snoozed_until); restart and cancel(for:) work without it.

Firing

The sweep fires due rows oldest first (notifications.reminders.batch per sweep), each claimed by compare-and-set. In order: type or rule gone → cancelled; subject gone → subject_deleted; anchor changed → re-timed or passed; condition false → condition; more than reminders.max_lateness (P1D) overdue and the anchor already passed → skipped (late). Then the send runs with the reminder’s idempotency key (access per recipient), the row is sent, the escalation chain is armed and ReminderFired fires. A row still firing after reminders.lease goes back to pending, and its re-fire sends nothing twice; a send that throws is retried by the next sweeps and cancelled after three attempts. The payload’s data holds the signed offset (['reminder' => '-P30D']) and its reminder holds the ReminderReference.

Escalations

Each level is a row due after the previous send. At fire: acknowledged → cancelled; subject gone or condition false → cancelled; otherwise the level’s recipients get the type (or the level’s type:) flagged as escalated, in their own lane — never folded into the original item or mail — and the next level is armed — unless an acknowledgement landed while the level was being sent, which ends the chain there. EscalationFired fires. A level’s own type: must be registered and take the subject; a type rule’s escalation is checked once the app has booted (or when a type is added later), so a bad level fails at boot instead of at fire time. Each fired reminder arms its own chain; send-level chains are one per subject and type (see Sending).

Acknowledgement

Notifications::for($contract)->acknowledge('contract.expiring', by: $user);   // or acknowledge() for every type
Notifications::reminders()->acknowledge($contract, 'contract.expiring', by: $user);

It stamps the reminders and escalations of the subject (and type) that already went out and cancels their pending escalations. A repeating rule’s chains end too: with by: only that recipient’s chain (and the escalations it armed) — everyone else keeps being reminded; without by: every chain of the subject ends. A by: who has no chain acknowledges the one-off reminders and send escalations as before and leaves the chains running. Pending later offsets are not stamped: they still fire and their own escalation runs — an acknowledged 30-day reminder silences neither the 7-day one nor its escalation to the managers. A re-armed reminder starts unacknowledged. Rules with acknowledgedOnRead() also acknowledge when any recipient marks the reminder’s inbox item read, but only while that reader can still see the subject. POST /inbox/{item}/acknowledge does the same after the same access check, for the type the chain is stored under — an item from an escalation level with its own type: acknowledges that chain; host code acknowledging such an item passes the chain’s original type. Notifications::for($subject)->acknowledge(by:) is trusted host code: it checks nothing, so call it only for a user you have authorized.

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.