NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Notifications for Laravel

Pripomienky a eskalácie

Pravidlá pripomienok patria druhu so subject() a vzťahujú sa na jeho dátumový atribút:

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'
    }
}
BuilderVýznam
Reminder::before($attribute, ...$offsets) / after(...)Kotva ∓ posun (ISO-8601 alebo relatívne), 1–25 kladných posunov.
Reminder::at(CarbonInterface $when)Absolútny čas — len pre jednorazové pripomienky.
->key('expiry')Stabilný kľúč pravidla (predvolene {attribute}:{direction}); dve pravidlá na jednom atribúte a smere potrebujú rôzne kľúče.
->to($recipients)Koho pripomienka upozorní; pravidlo bez to() je šablóna pre schedule($type, to: …).
->while(fn (Model $subject): bool)Overí sa pri odoslaní s čerstvým subjektom; false zruší (condition).
->escalate(after:, to:, type: null)Opakovateľné — reťaz úrovní. Nečitateľné alebo nekladné oneskorenie vyhodí výnimku okamžite; rovnako type: úrovne, ktorý nie je zaregistrovaný alebo neprijíma daný subjekt.
->acknowledgedOnRead()Prečítanie položky pripomienky v schránke ju potvrdí.
->rearm(false)Neobnovovať odoslané pripomienky, keď sa kotva posunie neskôr (predvolene sa obnovia).
Reminder::every($interval)Opakované pravidlo (od 1.3.0) s from(), startingAfter(), times() a until() — pozrite Opakované pripomienky.
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

Pravidlá sa overujú pri registrácii: druh má subjekt, atribút nie je prázdny, 1–25 kladných posunov, kľúče pravidiel sú v druhu unikátne, žiadne at() v pravidle druhu. Kotva sa číta cez váš cast a prevedie sa do UTC. Časové posuny (PT…) sú absolútne; kalendárne (P…D/W/M/Y) sa aplikujú na miestny čas kotvy v app.timezone, takže „7 dní pred 09:00“ zostane 09:00 aj cez zmenu času. Mesiace a roky nikdy nepretečú: zarovnajú sa na posledný deň cieľového mesiaca (P1M pred 31. marcom je 28. február, P1Y po 29. februári je 28. február) a potom sa uplatnia dni (P1M1D pred 31. marcom je 27. február).

Sledovanie dátumu

S traitom HasNotificationReminders na subjekte (pozrite Modely príjemcov a subjektov) sa pri každom uložení vykoná synchronizácia. Pre každé pravidlo a posun:

  • Kotva vymazaná → čakajúce riadky sa zrušia (anchor_cleared).
  • Čakajúci riadok s posunutým časom → prečasuje sa (ReminderRescheduled), alebo zruší (passed), ak je nový čas už v minulosti — posun kotvy dopredu nikdy neodošle vynechané posuny naraz. Riadok zrušený ako passed sa pre svoj dátum nikdy nespustil, takže keď sa dátum vráti späť, naplánuje sa znova.
  • Žiadny čakajúci riadok → naplánuje sa, ak je čas v budúcnosti, pokiaľ už riadok pre presne túto kotvu neskončil; odoslaný riadok staršej kotvy sa obnoví (predĺženie). Minulé posuny sa nikdy nedopĺňajú.
  • Unikátny kľúč zaistí, že dve súbežné synchronizácie naplánujú jeden riadok; konflikt nikdy nevyhodí výnimku.
  • Update cez query builder obíde udalosti modelu: krok odoslania kotvu znova prečíta, takže zastaraný čas sa prečasuje namiesto odoslania.

Výslovné API a jednorazové pripomienky

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

Jednorazové pripomienky si ukladajú príjemcov aj dáta; ukotvená sleduje svoju kotvu ako pripomienka z pravidla a posuny, ktoré sú už v minulosti, sa preskočia — remind() vráti len naplánované riadky, [] keď všetky posuny prešli; čas z at() sa naplánuje tak, ako je. Druhé remind() s rovnakým kľúčom (->key(), inak atribút + posun, alebo čas) nahradí čakajúci riadok; s ->key() a viacerými posunmi má každý posun pod týmto kľúčom vlastný riadok a opakované volanie nahradí každý z nich. remind() alebo schedule(), ktoré prídu práve pri odosielaní tej istej pripomienky, počkajú ako jeden riadok navyše, ktorý nahradia ďalšie volania a ktorý po skončení odosielania prevezme kľúč — nikdy nevznikne druhá kópia, ktorá by odišla dvakrát. Druh bez subject() prijme jednorazové pripomienky na ľubovoľnom modeli (report.ready vyššie): pripomienka odíde bez subjektu — model ju len ukotvuje a vlastní, jeho zmazanie ju zruší — a ukotvená sleduje kotvu pri uložení, ak model používa HasNotificationReminders. remind() odmietne subjekt inej triedy, než je subject() druhu (InvalidNotificationSubjectException). Jednorazové pripomienky neberú podmienku, eskaláciu ani acknowledgedOnRead() — pravidlo s niektorou z nich vyhodí InvalidReminderRuleException; na to deklarujte pravidlo na druhu. Príjemcovia musia byť uložiteľní (bez closures). Pre subjekty, ktoré existovali pred pridaním druhu, spustite notifications:reminders:sync — backfill() synchronizuje po dávkach 200 a pre druh bez triedy subjektu alebo bez pravidiel pripomienok vyhodí InvalidReminderRuleException.

Opakované pripomienky

Od verzie 1.3.0. „Každých 7 dní pripomínať smernicu každému, kto ju ešte nepotvrdil“ je pravidlo druhu postavené cez 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
  • Jedna reťaz na príjemcu. Každý príjemca má vlastnú reťaz riadkov (morph príjemcu na riadku); otvorený je vždy len jeden riadok reťaze a jeho odoslanie zapíše ďalší (level = poradie pripomienky), takže fireDue() zostáva obyčajným dopytom na splatnosť. Kľúč pravidla je {attribute}:every, bez from() scheduled:every; dve opakované pravidlá na jednej kotve potrebujú ->key().
  • Termíny sa počítajú od kotvy: kotva + prvé oneskorenie + n × interval, s ohľadom na kalendár ako pri posunoch (09:00 miestneho času zostane 09:00 aj cez zmenu času). Oneskorený sweep reťaz nikdy neposunie ani nepošle dávku naraz — pripomienka oneskorená viac než reminders.max_lateness sa preskočí (late) a reťaz pokračuje najbližším budúcim termínom.
  • Reťaz skončí, keď ju príjemca potvrdí, while() vráti false (condition), pripomienky subjektu sa zrušia (cancel() alebo zmazanie), zrušia sa pripomienky príjemcu (cancel(for:), od 1.4.0), kotva sa vymaže (anchor_cleared), dosiahne sa times() alebo ďalší termín padne za until(). Potvrdenie, ktoré príde počas odosielania pripomienky, ukončí reťaz po nej.
  • Opätovné plánovanie pridá len nováčikov: schedule() — alebo sync() pri pravidle s ->to() — spustí reťaz každému príjemcovi, ktorý ju ešte nemá. Bežiaca reťaz zostane bez zásahu a reťaz, ktorá pre aktuálnu kotvu už prebehla (potvrdená, ukončená, zrušená), sa znova nespustí — ak neodovzdáte restart: true (pozrite nižšie). Kto sa pridá neskôr, začne najbližším budúcim termínom reťaze — s from() zarovnaným na kotvu, bez neho na vlastný čas naplánovania. Reťaz ukotvená k naplánovaniu prebehne pre každého príjemcu raz.
  • Keď sa kotva zmení (sync(), uloženie s traitom alebo pri odoslaní), otvorený riadok sa prečasuje na prvý budúci termín novej kotvy. Ak sa posunie neskôr — znovu zverejnená smernica — ukončené reťaze začnú odznova na level 1; ->rearm(false) to vypne. Od 1.4.0 reaguje uloženie s traitom aj vtedy, keď sa zmenil len atribút from() opakovaného pravidla — koncept zverejnený neskôr tak spustí reťaze pravidla s ->to() a opätovné zverejnenie obnoví reťaze, ktoré už všetky skončili.
  • Eskalácia pripraví každú úroveň raz na reťaz: escalate('P10D', …) sa počíta od prvej pripomienky reťaze, escalate(3, …) — celé číslo, len pri opakovaných pravidlách — sa pripraví po 3. nepotvrdenej pripomienke a je splatná o jeden interval neskôr. Riadok eskalácie nesie príjemcu reťaze, takže jeho potvrdenie ju zruší a potvrdenie iného príjemcu nie.
  • Každé odoslanie funguje ako jednorazová pripomienka: kľúč idempotencie reminder:{id}, tiché hodiny, súhrny, preferencie aj prístup platia rovnako. Jeho data sú ['reminder' => 'P7D', 'occurrence' => n].
  • Opakované pravidlo je pravidlo druhu — remind() ho odmietne. from(), startingAfter(), times(), until() a escalate(int) na jednorazovom pravidle, nečitateľný či nekladný interval, záporné prvé oneskorenie alebo times(0) vyhodia InvalidReminderRuleException (invalid_repeat) priamo pri zápise.

Riadenie reťaze jedného príjemcu

Od verzie 1.4.0. Všetky tri idú cez manažéra — takže ich Notifications::fake() zaznamená —, sú idempotentné a zostávajú dohľadateľné cez existujúce udalosti:

$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) spustí novú reťaz každému uvedenému príjemcovi, ktorého reťaz skončila — potvrdená, while() false, zrušená, dosiahnuté times() / until() — aj pre tú istú kotvu. Nová reťaz sa počíta od pripomienky č. 1 (level 1, nový limit times(), eskalácie pripravené odznova) a začne najbližším budúcim termínom kotvy, nikdy termínom, ktorý ukončená reťaz už odoslala. Otvorená reťaz zostane, takže opakované volanie nič nezmení. while() sa tu neoveruje: ak je stále false, reťaz pri prvom odoslaní znova skončí. Obyčajné schedule() a sync() sa správajú ako vo verzii 1.3 — nič sa samo nereštartuje.
  • cancel($type = null, for: $recipient) zruší len čakajúce riadky reťaze daného príjemcu a eskalácie, ktoré jeho reťaz pripravila (ReminderCancelled, cancel_reason cancelled); bez druhu naprieč všetkými druhmi subjektu. Jednorazové pripomienky zdieľajú ich príjemcovia, preto zostanú bez zásahu. Vráti počet zrušených riadkov — 0 pre príjemcu bez otvorenej reťaze alebo pri druhom volaní. Neskoršie sync() či obyčajné schedule() reťaz pre tú istú kotvu nevrátia; restart: true áno, rovnako ako kotva posunutá neskôr.
  • snooze($type, $recipient, until: $instant) presunie otvorenú pripomienku daného príjemcu pre každé opakované pravidlo druhu na $until; ďalšie pripomienky nasledujú v celých intervaloch po ňom ($until + n × interval, s ohľadom na kalendár), kým ostatní príjemcovia si ponechajú pôvodné termíny. Vráti počet zmenených reťazí a spustí ReminderRescheduled. Riadok si ponechá level, takže times() stále počíta každú pripomienku a escalate(n) sa stále pripraví po n-tej; už pripravené eskalácie sa neposúvajú. Odloženie sa uloží na riadok (snoozed_until, NotificationReminder::isSnoozed()) a prenesie sa na každý ďalší riadok reťaze.

Pravidlá odloženia: príjemca bez otvorenej reťaze zostane bez zásahu (0) — odloženie reťaz nikdy nespustí, na to slúži restart: true; odloženie na už nastavený čas vráti tiež 0. $until po until() pravidla reťaz ukončí (passed). Keď sa kotva posunie, otvorený riadok sa prečasuje na termíny novej kotvy a odloženie sa zahodí — nové zverejnenie znamená nový rytmus. Pripomienka, ktorá sa práve odosiela, sa neodloží. $until, ktorý nie je v budúcnosti, alebo druh bez opakovaného pravidla sa odmietne vopred — aj pod fake — s InvalidReminderRuleException (invalid_snooze, 422); neznámy druh vyhodí UnknownNotificationTypeException. Odloženie potrebuje migráciu z verzie 1.4.0 (snoozed_until); restart a cancel(for:) fungujú aj bez nej.

Odosielanie

Sweep odosiela splatné riadky od najstarších (notifications.reminders.batch na sweep), každý prevzatý cez compare-and-set. V tomto poradí: druh či pravidlo neexistuje → zrušené; subjekt neexistuje → subject_deleted; kotva sa zmenila → prečasované alebo passed; podmienka false → condition; oneskorenie viac než reminders.max_lateness (P1D) a kotva už prešla → preskočené (late). Potom prebehne odoslanie s kľúčom idempotencie pripomienky (prístup pre každého príjemcu), riadok je sent, pripraví sa reťaz eskalácií a spustí sa ReminderFired. Riadok, ktorý sa po reminders.lease stále odosiela, sa vráti do pending a opakované odoslanie nič nepošle dvakrát; odoslanie, ktoré vyhodí výnimku, sa opakuje v ďalších sweepoch a po troch pokusoch sa zruší. data v payloade obsahuje posun so znamienkom (['reminder' => '-P30D']) a reminder obsahuje ReminderReference.

Eskalácie

Každá úroveň je riadok splatný after po predchádzajúcom odoslaní. Pri odoslaní: potvrdené → zrušené; subjekt neexistuje alebo podmienka je false → zrušené; inak príjemcovia úrovne dostanú druh (alebo type: danej úrovne) označený ako eskalácia, vo vlastnej dráhe — nikdy sa nezlúči s pôvodnou položkou ani e-mailom — a pripraví sa ďalšia úroveň — ibaže počas odosielania úrovne prišlo potvrdenie, ktoré reťaz ukončí. Spustí sa EscalationFired. Vlastný type: úrovne musí byť zaregistrovaný a prijímať subjekt; eskalácia v pravidle druhu sa overí po spustení aplikácie (alebo pri neskoršom pridaní druhu), takže chybná úroveň zlyhá pri štarte, nie pri odoslaní. Každá odoslaná pripomienka spustí vlastnú reťaz; reťaze z odoslania sú najviac jedna na subjekt a druh (pozrite Odosielanie).

Potvrdenie

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

Označí pripomienky a eskalácie subjektu (a druhu), ktoré už odišli, ako potvrdené a zruší ich čakajúce eskalácie. Skončia aj reťaze opakovaného pravidla: s by: len reťaz daného príjemcu (a eskalácie, ktoré pripravila) — ostatným pripomienky chodia ďalej; bez by: skončia všetky reťaze subjektu. by: bez vlastnej reťaze potvrdí jednorazové pripomienky a eskalácie z odoslania ako doteraz a reťaze nechá bežať. Čakajúce neskoršie posuny sa neoznačia: stále odídu a ich vlastná eskalácia prebehne — potvrdená 30-dňová pripomienka neumlčí 7-dňovú ani jej eskaláciu manažérom. Obnovená pripomienka začína nepotvrdená. Pravidlá s acknowledgedOnRead() sa potvrdia aj vtedy, keď ktorýkoľvek príjemca označí položku pripomienky ako prečítanú, ale len kým ten čitateľ subjekt stále vidí. POST /inbox/{item}/acknowledge robí to isté po rovnakej kontrole prístupu, pre druh, pod ktorým je reťaz uložená — položka z úrovne eskalácie s vlastným type: potvrdí túto reťaz; kód aplikácie, ktorý potvrdzuje takú položku, odovzdá pôvodný druh reťaze. Notifications::for($subject)->acknowledge(by:) je dôveryhodný kód aplikácie: nič neoveruje, preto ho volajte len pre používateľa, ktorého ste autorizovali.

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.