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

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

StavVýznam
pending → sending → sentBež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.
heldTiché 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.
digestOdložené do súhrnu používateľa.
cancelledrecipient_gone, unknown_type, subject_gone, no_access, muted (okrem povinných), revoked — overuje sa tesne pred odoslaním; rate_limited pri when_limited skip.
failedrender (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).
undeliverableno_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_recipient20 / PT1HKaždý typovaný e-mail jednému príjemcovi.
rate_limit.per_contextvypnuté (max null) / PT1HKaž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=on
List-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 + cestaNázovČo robí
GET /notifications/unsubscribe/{token}notifications.unsubscribe.showNič nemení — potvrdzovacia stránka, ktorej tlačidlo pošle POST, takže skenery odkazov nikoho neodhlásia.
POST /notifications/unsubscribe/{token}notifications.unsubscribeVypne 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
UnsubscribeOutcomeVýznam
UnsubscribedE-maily druhu sú teraz pre príjemcu vypnuté — rovnaký prepis pre druh ako preferences($user)->mute($type, Channel::Mail).
AlreadyUnsubscribedUž boli vypnuté alebo druh e-maily neposiela: nič sa nezmenilo.
RequiredDruh sa medzitým stal povinným: jeho e-maily zostávajú zapnuté.
GonePrí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 negative

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.