Inštalácia
Pridajte balík, publikujte jeho migrácie aj migrácie options-for-laravel (cez ne sa ukladajú preferencie) a spustite migráciu. Service provider sa načíta automaticky spolu s providermi balíkov Roundly, na ktorých stojí — crypto, enums, options a 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 migrateMigrácie sa len publikujú — provider žiadnu z nich nenačíta. Vznikne päť tabuliek v tomto poradí: notification_reminders, notification_inbox_items, notification_digest_runs, notification_deliveries a notification_receipts. Každý časový stĺpec je dateTime a každá hodnota je v UTC, takže neplatí limit MySQL 2038 a nevznikajú hodnoty nejednoznačné pri zmene času. Vlastnú tabuľku notifications Laravelu balík nikdy nepoužije.
Publikovanie môže urobiť aj inštalačný príkaz:
# Publishes the config and the migrations (refusing when a configured table already exists)
# and prints the schedule lines and trait snippets
php artisan notifications:install1. Naplánujte sweep
Podržané e-maily, e-maily na konci okna, opakované pokusy, súhrny, pripomienky aj eskalácie odchádzajú z jedného príkazu. Naplánujte ho každú minútu — balík sám nič neplánuje:
// routes/console.php
use Illuminate\Support\Facades\Schedule;
Schedule::command('notifications:sweep')->everyMinute()->withoutOverlapping(10)->onOneServer();
Schedule::command('notifications:prune')->daily();withoutOverlapping(10) je dôležité: predvolený mutex žije 24 hodín, takže zabitý sweep by inak na deň zastavil podržané e-maily, súhrny aj pripomienky. Každý krok sweepu preberá riadky cez compare-and-set, takže dva plánovače nikdy nepošlú jeden riadok dvakrát; onOneServer() len šetrí prácu. Spustite aj queue worker — e-maily, súhrny a veľké rozposielania idú do frontu, ak nie je vypnuté notifications.queue.enabled.
2. Typy kľúčov nastavte pred migráciou
Ak všade používate bigint id, predvolené hodnoty vyhovujú. Pri UUID alebo ULID kľúčoch ich nastavte pred 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 sa musí zhodovať s typom kľúča vašich používateľov aj s options.key_type. Pred každým zápisom sa každá morph hodnota overí voči svojmu typu kľúča a nezhoda vyhodí InvalidNotificationsConfigurationException s kľúčom konfigurácie a názvom modelu — nikdy surovú SQL chybu.
3. Urobte z User príjemcu
Príjemca je Eloquent model, ktorému sa dá poslať e-mail (Notifiable alebo RoutesNotifications z Laravelu, prípadne notifications.mail.address_resolver), je Authenticatable, ak sa druh spolieha na predvolenú kontrolu cez Gate, a používa 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 je pomenovaný tak, aby sa dal kombinovať s Notifiable: nekoliduje s notifications(), notify() ani unreadNotifications(). Bez e-mailovej adresy sa doručenie označí ako undeliverable — nikdy nespôsobí fatálnu chybu pri doručení.
4. Opíšte druh a pošlite ho
Druh potrebuje policy s oprávnením view na svojom subjekte (tu PurchaseRequest), skupinu, ktorá vie vymenovať svojich členov (Company s ProvidesNotificationRecipients), a príjemcu ako vyššie:
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
}Potom ho pošlite z ľubovoľnej funkcie — schránku, e-mail, preferencie, deduplikáciu, tiché hodiny aj prístup balík vyrieši za vás — a prečítajte schránku používateľa:
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();Publikovacie tagy
| Tag | Publikuje |
|---|---|
notifications-migrations | Sedem migrácií — pripomienky, položky schránky, súhrny, doručenia, potvrdenky a potom morph príjemcu pripomienok (1.3.0) a snoozed_until (1.4.0) — s časovou pečiatkou z publikovania. Povinné: provider žiadnu z nich nenačíta. |
options-migrations | Tabuľka options-for-laravel — ukladajú sa cez ňu preferencie. Povinné. |
notifications-config | config/notifications.php |
notifications-translations | lang/vendor/notifications/{en,sk}/{mail,digest,enums,exceptions,preferences,unsubscribe}.php |
notifications-views | Markdown view súhrnného e-mailu notifications::mail.digest a stránka odhlásenia notifications::unsubscribe. |
notifications-routes | routes/notifications.php a routes/unsubscribe.php — po publikovaní sa načítajú namiesto súborov balíka, stále za notifications.routes.enabled a 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 filesTabuľky
| Tabuľka | Obsahuje |
|---|---|
notification_inbox_items | Morph vzťahy príjemcu, subjektu, kontextu a aktéra, count, data, snímka nadpisu a url, unikátny open_key, collapse_until, reminder_id, časy prečítania a archivácie. |
notification_deliveries | Stav, unikátny open_key, window_ends_at, send_after, events_count, frekvencia / obdobie / beh súhrnu, šifrovaný interop payload (skrytý), notification_id, source. |
notification_reminders | Druh, typ, pravidlo, morph subjektu, kotva + posun + anchor_value, due_at, level, parent_id, uložení príjemcovia a dáta, unikátny active_key, potvrdenie + morph potvrdzujúceho od 1.3.0 morph príjemcu (nullable) opakovanej reťaze a od 1.4.0 snoozed_until. |
notification_digest_runs | Unikátne pre príjemcu, frekvenciu a obdobie. |
notification_receipts | Unikátne pre kľúč a príjemcu; bez soft deletes — evidencia. |
Preklady a popisy
notifications::mail, notifications::digest, notifications::enums, notifications::exceptions a notifications::preferences sú dodané v angličtine a slovenčine. Popisy vašich druhov a kategórií patria do vašich vlastných prekladov:
// 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',
],
];Kontrola nastavenia
php artisan notifications:doctor
php artisan about --only=notificationsDoctor nahlási rozdielne typy kľúčov, front sync, nezdieľaný store zámku preferencií, odkazy na odhlásenie bez https, nezdieľaný store limitu e-mailov, neplatné predvolené tiché hodiny, druhy bez policy či oprávnenia, problémy s interop mapou a model používateľa, ktorému sa nedá poslať e-mail (pozrite Príkazy). Sekcia about ukáže počet druhov, front (spojenie a názov len ako SET alebo DEFAULT), routes, List-Unsubscribe (ON alebo OFF), limit e-mailov (OFF, alebo ON s defer či skip), všetky štyri typy kľúčov (kľúč, subjekt, primárny kľúč a kontext), predvolený súhrn a počty interop — nikdy nič tajné.
Prechod na verziu 1.4
Verzia 1.4.0 pridáva riadenie opakovaných pripomienok pre jednotlivých príjemcov (pozrite Pripomienky a eskalácie). Publikujte a spustite novú migráciu 0007 — do notification_reminders pridá nullable stĺpec snoozed_until, je len doplňujúca a potrebuje ju iba snooze():
php artisan vendor:publish --tag="notifications-migrations" # adds 0007 — snoozed_until on notification_reminders
php artisan migrateJedna zmena správania: HasNotificationReminders sa pri uložení synchronizuje aj vtedy, keď sa zmenil len atribút from() opakovaného pravidla, takže neskoršie zverejnenie konceptu spustí reťaze pravidla s ->to() a opätovné zverejnenie obnoví reťaze, ktoré už všetky skončili.
Prechod z verzie 1.2
Verzia 1.3.0 pridáva opakované pripomienky. Publikujte a spustite novú migráciu — do notification_reminders pridá nullable morph príjemcu (podľa notifications.key_type), je len doplňujúca a existujúce pripomienky nemení:
php artisan vendor:publish --tag="notifications-migrations" # adds 0006_add_recipient_to_notification_reminders_table
php artisan migrate- acknowledge(by: $user) ukončí len opakovanú reťaz používateľa $user. Jednorazové pripomienky a eskalácie z odoslania sa potvrdzujú pre celý subjekt ako doteraz.
- Odoslania pripomienok a eskalácií teraz idú cez manažéra, takže ich Notifications::fake() zaznamená ako každé iné odoslanie. Doručovanie v produkcii sa nemení.
Prechod z verzie 1.1
Žiadna migrácia ani povinná zmena konfigurácie. Tri nové funkcie e-mailov nič nezmenia, kým ich nezapnete: odhlásenie jedným kliknutím aj limit e-mailov sú vypnuté a predvolený NullSuppressionList neblokuje nič (pozrite E-mail). Route na odhlásenie má vlastný súbor routes/unsubscribe.php, takže skôr publikovaný routes/notifications.php netreba upravovať:
# 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)- Stlmenie schránky celej kategórie pri vypnutom notifications.preferences.inbox_mutable teraz vyhodí LockedNotificationChannelException (422) — cez muteCategory($category, Channel::Inbox), PreferencesUpdate aj PATCH /preferences v categories.<category>.inbox — rovnako ako to isté stlmenie jedného druhu. Predtým sa uložil prepis, ktorý sa potom ignoroval.
- Vlastný type: úrovne eskalácie musí byť zaregistrovaný a prijímať eskalovaný subjekt: ->escalate(type: …) vyhodí InvalidReminderRuleException už pri volaní a eskalácia v pravidle druhu sa overí po spustení aplikácie. Taká úroveň sa predtým prijala a zlyhala až pri odoslaní, takže nikto eskaláciu nedostal.
- Položky schránky z eskalácií a pripomienok si úroveň eskalácie a odkaz na pripomienku ukladajú v data._notifications. API ani publicData() ho nikdy nevidia, no kód, ktorý číta $item->data priamo, tento kľúč pri takých položkách teraz nájde.
- Zápis preferencií, ktorý včas nezíska zámok používateľa, vyhodí PreferencesLockedException (423, preferences_locked) namiesto LockTimeoutException z Laravelu — PATCH /preferences odpovie 423 namiesto 500.
- Pod Notifications::fake() vráti send(Foo::class, …) SendResult, ktorého type je kľúč, a každá asercia s druhom prijme kľúč aj triedu (pozrite Testovanie).
Prechod z verzie 1.0
Žiadna migrácia ani zmena konfigurácie. Ručne môžu byť potrebné dve veci: publikovaný súbor routes nový endpoint DELETE /inbox/{item} sám nedostane a kód, ktorý vytváral manažéra alebo fake cez new s kontajnerom, musí argument vynechať:
// 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();- Vypnutie kanála, ktorý sa vypnúť nedá, teraz vyhodí LockedNotificationChannelException (422) — PATCH /preferences odpovie 422 pod channels.<type>.<channel> tam, kde predtým odpovedal 200 (pozrite Preferencie).
- Subjekt má pre každý druh najviac jednu otvorenú reťaz eskalácií z odoslania: opakované odoslania s ->escalate() sa pridajú k otvorenej reťazi namiesto toho, aby každé spustilo vlastnú (pozrite Pripomienky a eskalácie).
- Pod Notifications::fake() odoslanie, ktoré skutočný postup vopred odmietne, teraz vyhodí rovnakú výnimku namiesto toho, aby sa zaznamenalo (pozrite Testovanie).
- InboxItemResource vykreslí data ako [] pre položku, ktorej druh už nie je zaregistrovaný, a muted() vráti false pre druh, ktorý e-maily neposiela.
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.