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 migrate

Migrá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:install

1. 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`	Päť migrácií — pripomienky, položky schránky, súhrny, doručenia, potvrdenky — 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}.php
`notifications-views`	Markdown view súhrnného e-mailu notifications::mail.digest.
`notifications-routes`	routes/notifications.php — po publikovaní sa načíta namiesto súboru balíka, stále za notifications.routes.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 view
php artisan vendor:publish --tag="notifications-routes"         # routes/notifications.php — replaces the package's file

Tabuľ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.
`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=notifications

Doctor nahlási rozdielne typy kľúčov, front sync, nezdieľaný store zámku preferencií, 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, typy kľúčov, predvolený súhrn a počty interop — nikdy nič tajné.

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.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

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.

Ponuka do 48 hodín Prezrieť všetky balíky