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'
}
}| Builder | Vý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 recipientsPravidlá 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 runsJednorazové 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 kryptomienOdoslaní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.