E-maily idú cez mailové notifikácie Laravelu (TypedMailNotification) v jazyku príjemcu (HasLocalePreference::preferredLocale()).
Deduplikácia v rámci okna
Kľúč deduplikácie má rovnaké časti ako kľúč zlučovania v schránke, takže jedna položka schránky a jedno doručenie vždy patria k sebe:
- Leading (predvolené, notifications.mail.strategy) — prvá udalosť odošle e-mail hneď (alebo na konci tichých hodín); ďalšie udalosti v okne sa doň zlúčia a nič ďalšie neodošlú. Desať udalostí za päť minút → jeden e-mail.
- Trailing (mailStrategy(): MailStrategy::Trailing) — doručenie čaká prvú udalosť + okno; každá udalosť sa zlúči a odíde jeden e-mail s konečným počtom a najnovším obsahom.
- Urgentné druhy posielajú vždy hneď. E-mail, ktorý ešte neodišiel, pohltí ďalšie udalosti (Folded); odoslaný ich len spočíta (Deduplicated). Ak sa pred odoslaním zlúčilo viac udalostí, e-mail uvedie „a N ďalších aktualizácií“.
// Leading (default): the first event mails now; later ones in the window fold into it
Notifications::send('request.awaiting_approval', $request, $approver); // MailOutcome::Pending
Notifications::send('request.awaiting_approval', $request, $approver); // MailOutcome::Folded (or Deduplicated once sent)
// Trailing: one mail after the window, with the final count and the latest content
final class CommentPosted extends NotificationType
{
public function window(): ?string { return 'PT10M'; }
public function mailStrategy(): MailStrategy { return MailStrategy::Trailing; }
// …
}Životný cyklus doručenia
| Stav | Význam |
|---|---|
pending → sending → sent | Bežná cesta. DeliverMailJob prevezme riadok cez compare-and-set, takže opakovaná úloha ani druhý scheduler nič nepošle. E-mail nad limitom sa vráti do pending, kým sa limit neuvoľní (when_limited defer), a pokus sa mu vráti. |
held | Tiché hodiny — sweep ho uvoľní po ich skončení; pri doručení sa znova overí a ak medzitým začali tiché hodiny, znova sa podrží. Podržanie nikdy nespotrebuje pokus o odoslanie. |
digest | Odložené do súhrnu používateľa. |
cancelled | recipient_gone, unknown_type, subject_gone, no_access, muted (okrem povinných), revoked — overuje sa tesne pred odoslaním; rate_limited pri when_limited skip. |
failed | render (háčik druhu vyhodil výnimku — nahlásené, bez opakovania), transport (po mail.max_attempts s mail.backoff medzi pokusmi), unknown (po mail.lease sa stále odosiela — nikdy sa nepošle znova). |
undeliverable | no_address — resolver vrátil null alebo príjemca nemá trasu pre e-mail; suppressed — zoznam blokovaných adries blokuje adresu, na ktorú by e-mail išiel. |
Adresa sa určí ešte pred mailovým kanálom Laravelu: nakonfigurovaný resolver adries, inak routeNotificationFor('mail'). Po adrese sa overí zoznam blokovaných adries a — ak je zapnutý — limit e-mailov (pozrite nižšie). Pri vypnutom notifications.queue.enabled beží úloha priamo po commite; inak sa odošle na notifications.queue.connection / queue a sweep pošle splatné doručenie do frontu znova až po notifications.mail.lease, pre prípad, že sa úloha stratila — pri zahltenom fronte sa tak nehromadia duplicitné úlohy. Udalosti: NotificationMailSent, NotificationMailFailed, NotificationMailHeld, NotificationMailSuppressed, NotificationMailThrottled.
E-mail na konci okna podržaný počas tichých hodín zostane za svojím oknom aj vtedy, keď používateľ zmení tiché hodiny alebo časové pásmo, takže stále nesie konečný počet okna. E-mail označený ako odoslaný v rámci okna si deduplikačný kľúč ponechá bez jeho zápisu, takže iný e-mail, ktorý medzitým kľúč prevzal, nikdy neoznačí doručený riadok ako zlyhaný.
Vykreslenie
Predmet = title(); oslovenie (s menom príjemcu, ak ho má); prvý riadok = body() (inak nadpis); „a N ďalších aktualizácií“ pri zlúčení; tlačidlo akcie (url() + actionText(), len absolútne http(s)); pätička — upozornenie na povinnosť pri povinných druhoch, inak odkaz na preferencie, ak je nastavené notifications.mail.preferences_url (URL alebo názov route); nakoniec háčik mail($message, $payload) druhu. Text ide cez markdown šablónu Laravelu, ktorá ho escapuje. V teste aplikácie to overíte takto:
use Illuminate\Support\Facades\Notification;
use RoundlyConsulting\Notifications\Mail\TypedMailNotification;
Notification::assertSentTo($user, TypedMailNotification::class, fn ($n) => $n->type === 'security.alert'
&& $n->message->subject === 'Security alert');Minimálny e-mail pre citlivé subjekty
Ak sensitive($subject) druhu vráti true a notifications.mail.minimal_for_sensitive je zapnuté (predvolené), e-mail obsahuje len minimalTitle() („New notification from :app“), jeden riadok a tlačidlo — body() ani mail() sa nevolajú. Riadky citlivých položiek v súhrne používajú tiež minimálny text. Schránky sa to netýka: je za vaším prihlásením.
Resolver adries
notifications.mail.address_resolver určuje ResolvesMailAddress, ktorý rozhodne o adrese každého e-mailu balíka — typovaných aj súhrnov; pri súhrne je payload null. Reťazec pošle na danú adresu; null označí doručenie ako undeliverable (súhrn zlyhá ako no_address). S contacts-for-laravel idú e-maily na primárny e-mailový kontakt používateľa:
class User extends Authenticatable
{
use HasContacts;
use Notifiable;
use ReceivesNotifications;
use RoutesNotificationsViaContacts; // mail goes to the primary email contact
}Ak chcete len overené adresy, naviažte resolver — používateľ bez overeného primárneho e-mailu potom dostane undeliverable a ani súhrn:
use Illuminate\Database\Eloquent\Model;
use RoundlyConsulting\Contacts\Enums\ContactType;
use RoundlyConsulting\Notifications\Contracts\ResolvesMailAddress;
use RoundlyConsulting\Notifications\NotificationPayload;
final class VerifiedEmailResolver implements ResolvesMailAddress
{
public function address(Model $recipient, ?NotificationPayload $payload): ?string // null payload = a digest
{
$contact = $recipient->primaryContact(ContactType::Email);
return $contact?->verified_at !== null ? $contact->value : null;
}
}
// config/notifications.php
'mail' => ['address_resolver' => App\Notifications\VerifiedEmailResolver::class],Zoznam blokovaných adries
SuppressionList — isSuppressed(string $address): bool — sa pýta pred každým typovaným e-mailom a súhrnom na každú adresu, na ktorú by e-mail išiel: adresu z resolvera alebo každú adresu, ktorú vráti routeNotificationFor('mail') (reťazec, zoznam, objekty s email alebo mapa address => name), orezanú, s ponechanou veľkosťou písmen — ak to váš zoznam potrebuje, porovnávajte bez ohľadu na veľkosť písmen. Jedna blokovaná adresa zastaví celý e-mail: doručenie skončí ako undeliverable (suppressed), súhrn ako failed a jeho položky ako failed (suppressed), a spustí sa NotificationMailSuppressed s príjemcom, blokovanými adresami a doručením alebo súhrnom. Mapované e-maily iných balíkov (interop) sa neoverujú.
use RoundlyConsulting\Notifications\Contracts\SuppressionList;
final class BouncedAddresses implements SuppressionList
{
public function isSuppressed(string $address): bool
{
return Bounce::query()->where('email', strtolower($address))->exists();
}
}
// config/notifications.php
'mail' => ['suppression_list' => App\Mail\BouncedAddresses::class],Naviažete ho cez notifications.mail.suppression_list alebo v kontajneri — naviazanie kontraktu v providere aplikácie či iného balíka má prednosť. Predvolený NullSuppressionList neblokuje nič. Overenie, ktoré vyhodí výnimku (databáza zoznamu nebeží), je chyba transportu: opakuje sa a potom skončí ako failed (transport) — e-mail nikdy neodíde neoverený. Trieda, ktorá kontrakt neimplementuje, vyhodí pri vytvorení InvalidConfigurationException z toolkitu s názvom kľúča.
Limit e-mailov (voliteľný)
Pri zapnutom notifications.mail.rate_limit.enabled sa tesne pred odovzdaním typovaného e-mailu mailerovi opýta kontrakt ThrottlesMail — s príjemcom, druhom, kľúčom kontextu doručenia a id doručenia. Null e-mail odošle a započíta; čas znamená, že je nad limitom až dovtedy, a nič sa nezapočíta. Potom podľa rate_limit.when_limited:
- defer (predvolené) — doručenie sa vráti do pending so send_after na daný čas (aspoň o sekundu neskôr) a pokus sa mu vráti ako pri podržaní počas tichých hodín; sweep ho vtedy odošle a ďalšie udalosti jeho okna sa doň stále zlučujú.
- skip — doručenie sa zruší (rate_limited).
V oboch prípadoch sa spustí NotificationMailThrottled (delivery, until, deferred). Súhrny a mapované e-maily iných balíkov sa neobmedzujú a urgentné druhy nikdy. Predvolený DefaultMailThrottle počíta cez RateLimiter Laravelu — store cache.limiter, inak predvolenú cache; použite store zdieľaný medzi servermi, doctor upozorní na array a file:
| Kľúč | Predvolené (max / per) | Počíta |
|---|---|---|
rate_limit.per_recipient | 20 / PT1H | Každý typovaný e-mail jednému príjemcovi. |
rate_limit.per_context | vypnuté (max null) / PT1H | Každý typovaný e-mail v jednom kontexte, bez ohľadu na príjemcu. |
// .env
NOTIFICATIONS_MAIL_RATE_LIMIT=on
// config/notifications.php
'mail' => [
'rate_limit' => [
'enabled' => env('NOTIFICATIONS_MAIL_RATE_LIMIT', 'off'),
'throttle' => DefaultMailThrottle::class, // or your own ThrottlesMail
'per_recipient' => ['max' => 20, 'per' => 'PT1H'],
'per_context' => ['max' => 200, 'per' => 'PT1H'], // null max: off (the default)
'when_limited' => 'defer', // or 'skip'
],
],Prázdne max limit vypne. Každý limit sa počíta najprv pripočítaním — cache pripočítava atomicky — takže dva workery si nikdy nevezmú posledné miesto obaja a e-mail odmietnutý jedným limitom vráti, čo započítal v druhom. E-mail, ktorého transport potom zlyhá, sa stále ráta. Pre iné pravidlá (podľa druhu, podľa príjemcu a kontextu, podľa plánu tenanta) naviažte vlastný ThrottlesMail cez rate_limit.throttle:
namespace RoundlyConsulting\Notifications\Contracts;
use Carbon\CarbonImmutable;
use RoundlyConsulting\Notifications\DataTransferObjects\MailAttempt;
interface ThrottlesMail
{
// null: send now (and count it). A time: over a limit until then — nothing is counted,
// the mail is deferred to that time or skipped (rate_limit.when_limited)
public function attempt(MailAttempt $attempt): ?CarbonImmutable;
}
// MailAttempt: recipient (Model), type (NotificationType), contextKey (?string), deliveryId (int|string)use RoundlyConsulting\Notifications\Events\NotificationMailSuppressed;
use RoundlyConsulting\Notifications\Events\NotificationMailThrottled;
Event::listen(NotificationMailSuppressed::class, fn (NotificationMailSuppressed $event) => Log::info('Mail suppressed', [
'addresses' => $event->addresses, // list<string>
'delivery' => $event->delivery?->getKey(), // a typed mail…
'digest_run' => $event->digestRun?->getKey(), // …or a digest
]));
Event::listen(NotificationMailThrottled::class, fn (NotificationMailThrottled $event) => $event->deferred
? Log::info('Mail deferred until '.$event->until->toIso8601String())
: Log::info('Mail skipped (rate_limited)'));Odhlásenie jedným kliknutím (voliteľné)
Pri zapnutom notifications.mail.list_unsubscribe.enabled nesie e-mail každého druhu, ktorý si príjemca môže vypnúť — nikdy nie povinného — hlavičku List-Unsubscribe podľa RFC 2369 a cez https aj one-click hlavičku podľa RFC 8058:
NOTIFICATIONS_LIST_UNSUBSCRIBE=onList-Unsubscribe: <https://app.example/notifications/unsubscribe/{token}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click// config/notifications.php
'mail' => [
'list_unsubscribe' => [
'enabled' => env('NOTIFICATIONS_LIST_UNSUBSCRIBE', 'off'),
'middleware' => [], // never 'web': its CSRF check refuses a mail client's POST
'ttl' => null, // ISO-8601, e.g. 'P90D'; null: links never expire
],
],- One-click hlavička potrebuje https odkaz (https APP_URL); cez http sa pridá len List-Unsubscribe a doctor upozorní. E-mailoví klienti a poskytovatelia vyžadujú, aby boli hlavičky podpísané DKIM — to je úloha vášho nastavenia e-mailov.
- Súhrny nenesú ani jednu hlavičku: súhrn mieša druhy a jeho vypnutie by posielalo položky jednotlivo — na to slúži odkaz na preferencie v pätičke.
- Token je prihlasovací údaj: príjemca, druh a voliteľná expirácia (list_unsubscribe.ttl), zašifrované a podpísané kľúčom aplikácie cez encrypter Laravelu. Nedá sa prečítať ani sfalšovať, neobsahuje názov triedy a app.previous_keys udržia staré odkazy funkčné aj po rotácii kľúča.
- Uplatnenie odkazu vypne príjemcovi e-maily daného druhu — rovnaký prepis pre druh, aký zapíše preferences($user)->mute($type, Channel::Mail). Schránka položku ponechá, obrazovka nastavení zmenu zobrazí a dá sa vrátiť, a spustí sa NotificationPreferenceChanged.
Route (<routes.prefix>/unsubscribe/{token}) sa načíta len pri zapnutej funkcii, nezávisle od routes.enabled, a nemá prihlásenie, session ani CSRF — list_unsubscribe.middleware je []; nikdy nepridávajte web. Stránky sú čisté HTML v jazyku príjemcu (view notifications::unsubscribe, po anglicky a po slovensky):
| Metóda + cesta | Názov | Čo robí |
|---|---|---|
GET /notifications/unsubscribe/{token} | notifications.unsubscribe.show | Nič nemení — potvrdzovacia stránka, ktorej tlačidlo pošle POST, takže skenery odkazov nikoho neodhlásia. |
POST /notifications/unsubscribe/{token} | notifications.unsubscribe | Vypne e-maily druhu a vždy odpovie 200 s malou stránkou — idempotentné. Pozmenený, cudzí alebo expirovaný token je 403; obsadený zámok preferencií je 423 a klient to skúsi znova. |
Ak chcete zmeniť cestu, publikujte routes (--tag=notifications-routes), alebo si postavte vlastný endpoint nad accessorom:
use RoundlyConsulting\Notifications\Enums\UnsubscribeOutcome;
Notifications::unsubscribe()->url($user, 'comment.posted'); // ?string — for your own mail or page
Notifications::unsubscribe()->claim($token); // UnsubscribeClaim {recipient, type}, changes nothing
$result = Notifications::unsubscribe()->redeem($token); // UnsubscribeResult {outcome, type, recipient}
$result->outcome === UnsubscribeOutcome::Unsubscribed; // or AlreadyUnsubscribed, Required, Gone
// claim() and redeem() throw InvalidUnsubscribeTokenException (403) for a bad token| UnsubscribeOutcome | Význam |
|---|---|
Unsubscribed | E-maily druhu sú teraz pre príjemcu vypnuté — rovnaký prepis pre druh ako preferences($user)->mute($type, Channel::Mail). |
AlreadyUnsubscribed | Už boli vypnuté alebo druh e-maily neposiela: nič sa nezmenilo. |
Required | Druh sa medzitým stal povinným: jeho e-maily zostávajú zapnuté. |
Gone | Príjemca alebo druh už neexistuje. |
Pod Notifications::fake() sa uplatnenie zaznamená s príjemcom a druhom z odkazu a zlý token stále vyhodí výnimku:
$fake = Notifications::fake();
Notifications::unsubscribe()->redeem($token); // or the one-click POST — the controller goes through the manager
$fake->assertUnsubscribed($user, 'comment.posted'); // recipient and type optional; a key or a class
// $fake->assertNothingUnsubscribed(); // the negativePrejavte 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.