Notifiche

• Introduzione
• Generazione delle Notifiche
• Invio delle Notifiche
• Notifiche Email
• Notifiche email in Markdown
• Notifiche nel Database
• Broadcast Notifications
• Notifiche SMS
• Notifiche Slack
• Localizzazione delle notifiche
• Test
• Eventi di Notifica
• Canali Personalizzati

Introduzione

Oltre al supporto per l’invio di email, Laravel offre la possibilità di inviare notifiche attraverso diversi canali di consegna, inclusi email, SMS (tramite Vonage, precedentemente noto come Nexmo) e Slack. Inoltre, sono stati creati vari canali di notifica sviluppati dalla community per inviare notifiche su decine di canali differenti! Le notifiche possono anche essere memorizzate in un database per essere visualizzate nella tua interfaccia web.

In genere, le notifiche dovrebbero essere messaggi brevi e informativi che avvisano gli utenti di qualcosa che è accaduto nella tua applicazione. Ad esempio, se stai sviluppando un’applicazione di fatturazione, potresti inviare una notifica "Fattura Pagata" ai tuoi utenti tramite i canali email e SMS.

Generazione delle Notifiche

In Laravel, ogni notifica è rappresentata da una singola classe che di solito si trova nella directory app/Notifications. Non preoccuparti se non vedi questa directory nella tua applicazione: verrà creata automaticamente quando esegui il comando Artisan make:notification:

php artisan make:notification InvoicePaid

Questo comando aggiungerà una nuova classe di notifica nella directory app/Notifications. Ogni classe di notifica include un metodo via e diversi metodi per costruire il messaggio, come toMail o toDatabase, che trasformano la notifica in un messaggio adatto per quel canale specifico.

Invio delle Notifiche

Utilizzo del Trait Notifiable

Le notifiche possono essere inviate in due modi: usando il metodo notify del trait Notifiable oppure utilizzando la facade Notification. Il trait Notifiable è incluso di default nel modello App\Models\User della tua applicazione:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;
}

Il metodo notify fornito da questo trait si aspetta di ricevere un’istanza di notifica:

use App\Notifications\InvoicePaid;

$user->notify(new InvoicePaid($invoice));

Ricorda, puoi usare il trait Notifiable su qualsiasi tuo modello. Non sei limitato a includerlo solo nel tuo modello User.

Utilizzare la Facade Notification

In alternativa, puoi inviare notifiche tramite la facade Notification. Questo metodo è utile quando devi inviare una notifica a più entità notificabili, come una collezione di utenti. Per inviare notifiche usando la facade, passa tutte le entità notificabili e l’istanza della notifica al metodo send:

use Illuminate\Support\Facades\Notification;

Notification::send($users, new InvoicePaid($invoice));

Puoi anche inviare notifiche immediatamente utilizzando il metodo sendNow. Questo metodo invierà la notifica subito, anche se la notifica implementa l’interfaccia ShouldQueue:

Notification::sendNow($developers, new DeploymentCompleted($deployment));

Specificare i Canali di Invio

Ogni classe di notifica ha un metodo via che determina attraverso quali canali verrà inviata la notifica. Le notifiche possono essere inviate tramite i canali mail, database, broadcast, vonage e slack.

Se desideri utilizzare altri canali di invio come Telegram o Pusher, visita il sito Laravel Notification Channels gestito dalla comunità.

Il metodo via riceve un’istanza di $notifiable, che sarà un’istanza della classe a cui la notifica viene inviata. Puoi usare $notifiable per determinare su quali canali deve essere inviata la notifica:

    /**
     * Ottieni i canali di invio della notifica.
     *
     * @return array<int, string>
     */
    public function via(object $notifiable): array
    {
        return $notifiable->prefers_sms ? ['vonage'] : ['mail', 'database'];
    }

Accodare le Notifiche

Prima di accodare le notifiche, devi configurare la tua coda e avviare un worker.

Inviare notifiche può richiedere tempo, soprattutto se il canale deve effettuare una chiamata a un’API esterna per consegnare la notifica. Per velocizzare il tempo di risposta della tua applicazione, puoi accodare la notifica aggiungendo l’interfaccia ShouldQueue e il trait Queueable alla tua classe. L’interfaccia e il trait sono già importati per tutte le notifiche generate usando il comando make:notification, quindi puoi aggiungerli immediatamente alla tua classe di notifica:

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification implements ShouldQueue
{
    use Queueable;

    // ...
}

Una volta aggiunta l’interfaccia ShouldQueue alla tua notifica, puoi inviarla normalmente. Laravel rileverà l’interfaccia ShouldQueue nella classe e accoderà automaticamente la consegna della notifica:

$user->notify(new InvoicePaid($invoice));

Quando accodi le notifiche, verrà creato un job accodato per ogni combinazione di destinatario e canale. Ad esempio, verranno inviate sei richieste alla coda se la tua notifica ha tre destinatari e due canali.

Ritardare le Notifiche

Se vuoi ritardare la consegna della notifica, puoi concatenare il metodo delay all’istanza della tua notifica:

$delay = now()->addMinutes(10);

$user->notify((new InvoicePaid($invoice))->delay($delay));

Puoi passare un array al metodo delay per specificare l’importo del ritardo per canali specifici:

$user->notify((new InvoicePaid($invoice))->delay([
    'mail' => now()->addMinutes(5),
    'sms' => now()->addMinutes(10),
]));

In alternativa, puoi definire un metodo withDelay nella classe di notifica stessa. Il metodo withDelay dovrebbe restituire un array di nomi di canali e valori di ritardo:

/**
 * Determina il ritardo di consegna della notifica.
 *
 * @return array<string, \Illuminate\Support\Carbon>
 */
public function withDelay(object $notifiable): array
{
    return [
        'mail' => now()->addMinutes(5),
        'sms' => now()->addMinutes(10),
    ];
}

Personalizzare la Connessione della Coda per le Notifiche

Per impostazione predefinita, le notifiche in coda verranno gestite utilizzando la connessione della coda predefinita della tua applicazione. Se desideri specificare una connessione diversa da utilizzare per una notifica particolare, puoi chiamare il metodo onConnection nel costruttore della tua notifica:

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification implements ShouldQueue
{
    use Queueable;

    /**
     * Crea una nuova istanza di notifica.
     */
    public function __construct()
    {
        $this->onConnection('redis');
    }
}

Oppure, se desideri specificare una connessione di coda diversa da utilizzare per ogni canale di notifica supportato, puoi definire un metodo viaConnections nella tua notifica. Questo metodo deve restituire un array di coppie nome canale / nome connessione coda:

/**
 * Determina quali connessioni utilizzare per ogni canale di notifica.
 *
 * @return array<string, string>
 */
public function viaConnections(): array
{
    return [
        'mail' => 'redis',
        'database' => 'sync',
    ];
}

Personalizzazione delle Code dei Canali di Notifica

Se desideri specificare una coda particolare da utilizzare per ogni canale di notifica supportato, puoi definire un metodo viaQueues nella tua notifica. Questo metodo deve restituire un array di coppie nome canale / nome coda:

/**
 * Determina quali code dovrebbero essere usate per ogni canale di notifica.
 *
 * @return array<string, string>
 */
public function viaQueues(): array
{
    return [
        'mail' => 'mail-queue',
        'slack' => 'slack-queue',
    ];
}

Middleware per Notifiche in Coda

Le notifiche in coda possono definire middleware proprio come i job in coda. Per iniziare, definisci un metodo middleware nella tua classe di notifica. Il metodo middleware riceverà le variabili $notifiable e $channel, che ti permetteranno di personalizzare il middleware restituito in base alla destinazione della notifica:

    use Illuminate\Queue\Middleware\RateLimited;

    /**
     * Ottieni il middleware attraverso cui il job di notifica dovrebbe passare.
     *
     * @return array<int, object>
     */
    public function middleware(object $notifiable, string $channel)
    {
        return match ($channel) {
            'email' => [new RateLimited('postmark')],
            'slack' => [new RateLimited('slack')],
            default => [],
        };
    }

Notifiche in Coda e Transazioni di Database

Quando le notifiche in coda vengono inviate all’interno di transazioni di database, potrebbero essere processate dalla coda prima che la transazione sia stata confermata. In questo caso, eventuali aggiornamenti ai modelli o ai record del database realizzati durante la transazione potrebbero non essere ancora presenti nel database. Inoltre, i modelli o record creati all’interno della transazione potrebbero non esistere nel database. Se la tua notifica dipende da questi modelli, potrebbero verificarsi errori imprevisti quando il job che invia la notifica in coda viene elaborato.

Se l’opzione di configurazione after_commit della tua connessione alla coda è impostata su false, puoi comunque indicare che una particolare notifica in coda deve essere inviata dopo che tutte le transazioni di database aperte sono state confermate, chiamando il metodo afterCommit quando invii la notifica:

use App\Notifications\InvoicePaid;

$user->notify((new InvoicePaid($invoice))->afterCommit());

In alternativa, puoi chiamare il metodo afterCommit dal costruttore della tua notifica:

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification implements ShouldQueue
{
    use Queueable;

    /**
     * Crea una nuova istanza di notifica.
     */
    public function __construct()
    {
        $this->afterCommit();
    }
}

Per saperne di più su come risolvere questi problemi, consulta la documentazione relativa a job in coda e transazioni di database.

Come determinare se una notifica in coda deve essere inviata

Dopo che una notifica in coda è stata inviata per l’elaborazione in background, solitamente viene accettata da un lavoratore della coda e inviata al destinatario previsto.

Tuttavia, se desideri decidere definitivamente se una notifica in coda debba essere inviata dopo che viene elaborata da un lavoratore della coda, puoi definire un metodo shouldSend nella classe della notifica. Se questo metodo restituisce false, la notifica non verrà inviata:

/**
 * Determine if the notification should be sent.
 */
public function shouldSend(object $notifiable, string $channel): bool
{
    return $this->invoice->isPaid();
}

Notifiche su Richiesta

A volte potresti dover inviare una notifica a qualcuno che non è memorizzato come "utente" della tua applicazione. Usando il metodo route della facade Notification, puoi specificare informazioni di instradamento per notifiche ad-hoc prima di inviare la notifica:

use Illuminate\Broadcasting\Channel;
use Illuminate\Support\Facades\Notification;

Notification::route('mail', 'taylor@example.com')
            ->route('vonage', '5555555555')
            ->route('slack', '#slack-channel')
            ->route('broadcast', [new Channel('channel-name')])
            ->notify(new InvoicePaid($invoice));

Se desideri fornire il nome del destinatario quando invii una notifica su richiesta alla route mail, puoi fornire un array che contiene l’indirizzo email come chiave e il nome come valore del primo elemento nell’array:

Notification::route('mail', [
    'barrett@example.com' => 'Barrett Blair',
])->notify(new InvoicePaid($invoice));

Usando il metodo routes, puoi fornire informazioni di instradamento ad-hoc per più canali di notifica contemporaneamente:

Notification::routes([
    'mail' => ['barrett@example.com' => 'Barrett Blair'],
    'vonage' => '5555555555',
])->notify(new InvoicePaid($invoice));

Notifiche Email

Formattare i Messaggi Email

Se una notifica può essere inviata come email, dovresti definire un metodo toMail nella classe della notifica. Questo metodo riceverà un’entità $notifiable e dovrebbe restituire un’istanza di Illuminate\Notifications\Messages\MailMessage.

La classe MailMessage contiene alcuni metodi semplici per aiutarti a creare messaggi email transazionali. I messaggi email possono includere righe di testo e una "call to action". Vediamo un esempio di metodo toMail:

/**
 * Get the mail representation of the notification.
 */
public function toMail(object $notifiable): MailMessage
{
    $url = url('/invoice/'.$this->invoice->id);

    return (new MailMessage)
                ->greeting('Hello!')
                ->line('One of your invoices has been paid!')
                ->lineIf($this->amount > 0, "Amount paid: {$this->amount}")
                ->action('View Invoice', $url)
                ->line('Thank you for using our application!');
}

Notiamo che stiamo usando $this->invoice->id nel nostro metodo toMail. Puoi passare qualsiasi dato necessario alla notifica per generare il suo messaggio nel costruttore della notifica.

In questo esempio, abbiamo un saluto, una riga di testo, una call to action e un’altra riga di testo. Questi metodi forniti dall’oggetto MailMessage rendono semplice e veloce formattare email transazionali di piccole dimensioni. Il canale mail tradurrà poi i componenti del messaggio in un bel template email HTML reattivo con una versione in testo semplice. Ecco un esempio di email generata dal canale mail:

Quando invii notifiche via email, assicurati di impostare l’opzione name nel file di configurazione config/app.php. Questo valore sarà utilizzato nell’intestazione e nel piè di pagina dei messaggi di notifica via email.

Messaggi di Errore

Alcune notifiche informano gli utenti di errori, come un pagamento di fattura fallito. Puoi indicare che un messaggio di posta riguarda un errore chiamando il metodo error durante la creazione del messaggio. Quando usi il metodo error su un messaggio di posta, il pulsante di azione sarà rosso invece che nero:

/**
 * Get the mail representation of the notification.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
                ->error()
                ->subject('Invoice Payment Failed')
                ->line('...');
}

Altre opzioni di formattazione delle notifiche email

Invece di definire le "linee" di testo nella classe di notifica, puoi usare il metodo view per specificare un template personalizzato che verrà usato per generare l’email di notifica:

    /**
     * Get the mail representation of the notification.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)->view(
            'mail.invoice.paid', ['invoice' => $this->invoice]
        );
    }

Puoi specificare una view in testo semplice per il messaggio email passando il nome della view come secondo elemento di un array che viene fornito al metodo view:

    /**
     * Get the mail representation of the notification.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)->view(
            ['mail.invoice.paid', 'mail.invoice.paid-text'],
            ['invoice' => $this->invoice]
        );
    }

Oppure, se il tuo messaggio ha solo una view in testo semplice, puoi utilizzare il metodo text:

    /**
     * Get the mail representation of the notification.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)->text(
            'mail.invoice.paid-text', ['invoice' => $this->invoice]
        );
    }

Personalizzare il Mittente

Per impostazione predefinita, l’indirizzo del mittente / da dell’email è definito nel file di configurazione config/mail.php. Tuttavia, puoi specificare l’indirizzo da per una notifica specifica utilizzando il metodo from:

/**
 * Ottieni la rappresentazione email della notifica.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
                ->from('barrett@example.com', 'Barrett Blair')
                ->line('...');
}

Personalizzare il Destinatario

Quando si inviano notifiche tramite il canale mail, il sistema di notifiche cercherà automaticamente una proprietà email sull’entità notificabile. Puoi personalizzare quale indirizzo email viene utilizzato per inviare la notifica definendo un metodo routeNotificationForMail sull’entità notificabile:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Illuminate\Notifications\Notification;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Route notifications for the mail channel.
     *
     * @return  array<string, string>|string
     */
    public function routeNotificationForMail(Notification $notification): array|string
    {
        // Return email address only...
        return $this->email_address;

        // Return email address and name...
        return [$this->email_address => $this->name];
    }
}

Personalizzazione dell’Oggetto

Di default, l’oggetto dell’email è il nome della classe della notifica formattato in "Title Case". Quindi, se la tua classe di notifica si chiama InvoicePaid, l’oggetto dell’email sarà Invoice Paid. Se desideri specificare un oggetto diverso per il messaggio, puoi chiamare il metodo subject durante la creazione del messaggio:

    /**
     * Get the mail representation of the notification.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
                    ->subject('Notification Subject')
                    ->line('...');
    }

Personalizzare il Mailer

Per impostazione predefinita, la notifica email verrà inviata utilizzando il mailer predefinito definito nel file di configurazione config/mail.php. Tuttavia, puoi specificare un mailer diverso a runtime chiamando il metodo mailer durante la creazione del messaggio:

/**
 * Ottieni la rappresentazione email della notifica.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
                ->mailer('postmark')
                ->line('...');
}

Personalizzare i Modelli

Puoi modificare il modello HTML e testo semplice usato dalle notifiche email pubblicando le risorse del pacchetto di notifiche. Dopo aver eseguito questo comando, i modelli delle notifiche email si troveranno nella directory resources/views/vendor/notifications:

php artisan vendor:publish --tag=laravel-notifications

Allegati

Per aggiungere allegati a una notifica via email, usa il metodo attach mentre costruisci il tuo messaggio. Il metodo attach accetta il percorso assoluto del file come primo argomento:

    /**
     * Ottieni la rappresentazione email della notifica.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
                    ->greeting('Hello!')
                    ->attach('/path/to/file');
    }

Il metodo attach offerto dai messaggi di posta delle notifiche accetta anche oggetti attachable. Consulta la documentazione completa sugli oggetti attachable per saperne di più.

Quando alleghi file a un messaggio, puoi anche specificare il nome di visualizzazione e/o il tipo MIME passando un array come secondo argomento al metodo attach:

    /**
     * Ottieni la rappresentazione email della notifica.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
                    ->greeting('Hello!')
                    ->attach('/path/to/file', [
                        'as' => 'name.pdf',
                        'mime' => 'application/pdf',
                    ]);
    }

A differenza dell’allegare file negli oggetti mailable, non puoi allegare un file direttamente da un disco di archiviazione usando attachFromStorage. Dovresti invece usare il metodo attach con un percorso assoluto al file sul disco di archiviazione. In alternativa, puoi restituire un mailable dal metodo toMail:

    use App\Mail\InvoicePaid as InvoicePaidMailable;

    /**
     * Ottieni la rappresentazione email della notifica.
     */
    public function toMail(object $notifiable): Mailable
    {
        return (new InvoicePaidMailable($this->invoice))
                    ->to($notifiable->email)
                    ->attachFromStorage('/path/to/file');
    }

Quando necessario, puoi allegare più file a un messaggio usando il metodo attachMany:

    /**
     * Ottieni la rappresentazione email della notifica.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
                    ->greeting('Hello!')
                    ->attachMany([
                        '/path/to/forge.svg',
                        '/path/to/vapor.svg' => [
                            'as' => 'Logo.svg',
                            'mime' => 'image/svg+xml',
                        ],
                    ]);
    }

Allegati di Dati Grezzi

Il metodo attachData può essere utilizzato per allegare una stringa di byte grezzi come allegato. Quando si chiama il metodo attachData, devi fornire il nome del file che verrà assegnato all’allegato:

/**
 * Ottieni la rappresentazione della notifica via email.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
                ->greeting('Ciao!')
                ->attachData($this->pdf, 'name.pdf', [
                    'mime' => 'application/pdf',
                ]);
}

Aggiungere Tag e Metadati

Alcuni provider di email di terze parti come Mailgun e Postmark supportano i "tag" e i "metadati" dei messaggi, che possono essere utilizzati per raggruppare e tracciare le email inviate dalla tua applicazione. Puoi aggiungere tag e metadati a un messaggio email tramite i metodi tag e metadata:

/**
 * Ottieni la rappresentazione mail della notifica.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
                ->greeting('Commento Votato!')
                ->tag('upvote')
                ->metadata('comment_id', $this->comment->id);
}

Se la tua applicazione utilizza il driver Mailgun, puoi consultare la documentazione di Mailgun per maggiori informazioni su tag e metadati. Allo stesso modo, puoi consultare anche la documentazione di Postmark per maggiori informazioni sul loro supporto per tag e metadati.

Se la tua applicazione utilizza Amazon SES per inviare email, dovresti usare il metodo metadata per allegare i "tag" di SES al messaggio.

Personalizzare il Messaggio Symfony

Il metodo withSymfonyMessage della classe MailMessage ti permette di registrare una closure che verrà chiamata con l’istanza di Symfony Message prima di inviare il messaggio. Questo ti offre l’opportunità di personalizzare a fondo il messaggio prima che venga consegnato:

use Symfony\Component\Mime\Email;

/**
 * Ottieni la rappresentazione email della notifica.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
                ->withSymfonyMessage(function (Email $message) {
                    $message->getHeaders()->addTextHeader(
                        'Custom-Header', 'Header Value'
                    );
                });
}

Utilizzo dei Mailables

Se necessario, puoi restituire un oggetto mailable completo dal metodo toMail della tua notifica. Quando restituisci un Mailable invece di un MailMessage, dovrai specificare il destinatario del messaggio utilizzando il metodo to dell’oggetto mailable:

    use App\Mail\InvoicePaid as InvoicePaidMailable;
    use Illuminate\Mail\Mailable;
    
    /**
     * Get the mail representation of the notification.
     */
    public function toMail(object $notifiable): Mailable
    {
        return (new InvoicePaidMailable($this->invoice))
                    ->to($notifiable->email);
    }

Mailables e Notifiche su Richiesta

Se stai inviando una notifica su richiesta, l’istanza $notifiable fornita al metodo toMail sarà un’istanza di Illuminate\Notifications\AnonymousNotifiable, che offre un metodo routeNotificationFor utilizzabile per recuperare l’indirizzo email a cui la notifica su richiesta deve essere inviata:

use App\Mail\InvoicePaid as InvoicePaidMailable;
use Illuminate\Notifications\AnonymousNotifiable;
use Illuminate\Mail\Mailable;

/**
 * Ottieni la rappresentazione email della notifica.
 */
public function toMail(object $notifiable): Mailable
{
    $address = $notifiable instanceof AnonymousNotifiable
            ? $notifiable->routeNotificationFor('mail')
            : $notifiable->email;

    return (new InvoicePaidMailable($this->invoice))
                ->to($address);
}

Anteprima delle Notifiche Email

Quando crei un template per una notifica email, è utile poter visualizzare rapidamente il messaggio email nel tuo browser, proprio come fai con un normale template Blade. Per questo motivo, Laravel ti permette di restituire direttamente qualsiasi messaggio email generato da una notifica tramite una route o un controller. Quando viene restituito un MailMessage, questo verrà mostrato nel browser, permettendoti di vedere subito il design senza doverlo inviare a un vero indirizzo email:

use App\Models\Invoice;
use App\Notifications\InvoicePaid;

Route::get('/notification', function () {
    $invoice = Invoice::find(1);

    return (new InvoicePaid($invoice))
                ->toMail($invoice->user);
});

Notifiche email in Markdown

Le notifiche email in Markdown ti permettono di sfruttare i modelli predefiniti delle notifiche email, offrendo al contempo maggiore libertà per scrivere messaggi più lunghi e personalizzati. Poiché i messaggi sono scritti in Markdown, Laravel è in grado di generare template HTML belli e reattivi per i messaggi, creando automaticamente anche una controparte in testo semplice.

Generare il Messaggio

Per generare una notifica con un template Markdown corrispondente, puoi usare l’opzione --markdown del comando Artisan make:notification:

php artisan make:notification InvoicePaid --markdown=mail.invoice.paid

Come tutte le altre notifiche via mail, le notifiche che utilizzano template Markdown devono definire un metodo toMail nella loro classe di notifica. Tuttavia, invece di usare i metodi line e action per costruire la notifica, usa il metodo markdown per specificare il nome del template Markdown da utilizzare. Un array di dati che desideri rendere disponibili al template può essere passato come secondo argomento del metodo:

    /**
     * Ottieni la rappresentazione mail della notifica.
     */
    public function toMail(object $notifiable): MailMessage
    {
        $url = url('/invoice/'.$this->invoice->id);

        return (new MailMessage)
                    ->subject('Fattura Pagata')
                    ->markdown('mail.invoice.paid', ['url' => $url]);
    }

Scrivere il Messaggio

Le notifiche email in Markdown utilizzano una combinazione di componenti Blade e sintassi Markdown, che ti permettono di costruire facilmente notifiche sfruttando i componenti di notifica predefiniti di Laravel:

<x-mail::message>
# Fattura Pagata

La tua fattura è stata pagata!

<x-mail::button :url="$url">
Visualizza Fattura
</x-mail::button>

Grazie,<br>
{{ config('app.name') }}
</x-mail::message>

<a name="componente-pulsante"></a>
#### Componente Pulsante

Il componente button rende un link a bottone centrato. Il componente accetta due argomenti: un `url` e un `color` opzionale. I colori supportati sono `primary`, `green` e `red`. Puoi aggiungere quanti componenti button desideri a una notifica:

```blade
<x-mail::button :url="$url" color="green">
Visualizza Fattura
</x-mail::button>

Componente Panel

Il panel component visualizza il blocco di testo fornito in un pannello che ha un colore di sfondo leggermente diverso dal resto della notifica. Questo ti permette di attirare l’attenzione su un determinato blocco di testo:

<x-mail::panel>
This is the panel content.
</x-mail::panel>

Componente Tabella

Il componente tabella permette di trasformare una tabella Markdown in una tabella HTML. Accetta la tabella Markdown come contenuto. È supportato l’allineamento delle colonne utilizzando la sintassi di allineamento predefinita di Markdown:

<x-mail::table>
| Laravel       | Table         | Example       |
| ------------- | :-----------: | ------------: |
| Col 2 is      | Centered      | $10           |
| Col 3 is      | Right-Aligned | $20           |
</x-mail::table>

Personalizzazione dei Componenti

Puoi esportare tutti i componenti di notifica Markdown nella tua applicazione per personalizzarli. Per esportare i componenti, usa il comando Artisan vendor:publish per pubblicare il tag dell’asset laravel-mail:

php artisan vendor:publish --tag=laravel-mail

Questo comando pubblicherà i componenti mail Markdown nella directory resources/views/vendor/mail. La directory mail conterrà una cartella html e una text, ognuna con le rispettive rappresentazioni di ogni componente disponibile. Sei libero di personalizzare questi componenti come preferisci.

Personalizzare il CSS

Dopo aver esportato i componenti, la directory resources/views/vendor/mail/html/themes conterrà un file default.css. Puoi personalizzare il CSS in questo file e i tuoi stili saranno automaticamente incorporati nelle rappresentazioni HTML delle notifiche Markdown.

Se desideri creare un tema completamente nuovo per i componenti Markdown di Laravel, puoi posizionare un file CSS nella directory html/themes. Dopo aver nominato e salvato il tuo file CSS, aggiorna l’opzione theme nel file di configurazione mail per corrispondere al nome del tuo nuovo tema.

Per personalizzare il tema per una singola notifica, puoi chiamare il metodo theme durante la creazione del messaggio di posta della notifica. Il metodo theme accetta il nome del tema che deve essere utilizzato quando si invia la notifica:

    /**
     * Get the mail representation of the notification.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
                    ->theme('invoice')
                    ->subject('Invoice Paid')
                    ->markdown('mail.invoice.paid', ['url' => $url]);
    }

Notifiche nel Database

Prerequisiti

Il canale di notifica database memorizza le informazioni delle notifiche in una tabella del database. Questa tabella conterrà dati come il tipo di notifica e una struttura JSON che descrive la notifica.

Puoi interrogare la tabella per mostrare le notifiche nell’interfaccia utente della tua applicazione. Ma, prima, devi creare una tabella nel database per contenere le notifiche. Puoi usare il comando make:notifications-table per generare una migration con lo schema della tabella corretto:

php artisan make:notifications-table

php artisan migrate

Se i tuoi modelli notificabili usano UUID o chiavi primarie ULID, dovresti sostituire il metodo morphs con uuidMorphs o ulidMorphs nella migration della tabella delle notifiche.

Formattazione delle Notifiche nel Database

Se una notifica può essere memorizzata in una tabella del database, devi definire un metodo toDatabase o toArray nella classe della notifica. Questo metodo riceverà un’entità $notifiable e dovrebbe restituire un array PHP semplice. L’array restituito sarà codificato in JSON e memorizzato nella colonna data della tua tabella notifications. Vediamo un esempio di metodo toArray:

    /**
     * Ottieni la rappresentazione array della notifica.
     *
     * @return array<string, mixed>
     */
    public function toArray(object $notifiable): array
    {
        return [
            'invoice_id' => $this->invoice->id,
            'amount' => $this->invoice->amount,
        ];
    }

Quando la notifica viene memorizzata nel database della tua applicazione, la colonna type sarà popolata con il nome della classe della notifica. Tuttavia, puoi personalizzare questo comportamento definendo un metodo databaseType nella tua classe di notifica:

    /**
     * Ottieni il tipo di database della notifica.
     *
     * @return string
     */
    public function databaseType(object $notifiable): string
    {
        return 'invoice-paid';
    }

toDatabase vs. toArray

Il metodo toArray viene utilizzato anche dal canale broadcast per determinare quali dati trasmettere al frontend gestito da JavaScript. Se desideri avere due rappresentazioni array diverse per i canali database e broadcast, dovresti definire un metodo toDatabase invece di un metodo toArray.

Accesso alle Notifiche

Una volta che le notifiche sono salvate nel database, hai bisogno di un modo comodo per accedervi dalle tue entità notificabili. Il trait Illuminate\Notifications\Notifiable, incluso nel modello predefinito App\Models\User di Laravel, include una relazione notifications relazione Eloquent che restituisce le notifiche per l’entità. Per recuperare le notifiche, puoi accedere a questo metodo come qualsiasi altra relazione Eloquent. Per impostazione predefinita, le notifiche saranno ordinate in base al timestamp created_at con le notifiche più recenti all’inizio della collezione:

    $user = App\Models\User::find(1);

    foreach ($user->notifications as $notification) {
        echo $notification->type;
    }

Se vuoi recuperare solo le notifiche "non lette", puoi usare la relazione unreadNotifications. Anche in questo caso, le notifiche saranno ordinate per timestamp created_at con le più recenti all’inizio della collezione:

    $user = App\Models\User::find(1);

    foreach ($user->unreadNotifications as $notification) {
        echo $notification->type;
    }

Per accedere alle tue notifiche dal client JavaScript, dovresti definire un controller di notifiche per la tua applicazione che restituisce le notifiche per un’entità notificabile, come l’utente corrente. Puoi quindi effettuare una richiesta HTTP all’URL di quel controller dal tuo client JavaScript.

Contrassegnare le Notifiche come Lette

Tipicamente, vorrai contrassegnare una notifica come "letta" quando un utente la visualizza. Il trait Illuminate\Notifications\Notifiable fornisce un metodo markAsRead, che aggiorna la colonna read_at nel record del database della notifica:

    $user = App\Models\User::find(1);

    foreach ($user->unreadNotifications as $notification) {
        $notification->markAsRead();
    }

Tuttavia, invece di scorrere ogni notifica, puoi usare il metodo markAsRead direttamente su una collezione di notifiche:

    $user->unreadNotifications->markAsRead();

Puoi anche usare una query di aggiornamento di massa per contrassegnare tutte le notifiche come lette senza recuperarle dal database:

    $user = App\Models\User::find(1);

    $user->unreadNotifications()->update(['read_at' => now()]);

Puoi delete le notifiche per rimuoverle completamente dalla tabella:

    $user->notifications()->delete();

Broadcast Notifications

Prerequisiti

Prima di trasmettere notifiche, devi configurare e conoscere i servizi di event broadcasting di Laravel. L’event broadcasting permette di reagire agli eventi lato server di Laravel dal tuo frontend basato su JavaScript.

Formattazione delle Notifiche Broadcast

Il canale broadcast invia notifiche utilizzando i servizi di event broadcasting di Laravel, permettendo al tuo frontend basato su JavaScript di ricevere le notifiche in tempo reale. Se una notifica supporta il broadcast, puoi definire un metodo toBroadcast nella classe della notifica. Questo metodo riceverà un’entità $notifiable e dovrebbe restituire un’istanza di BroadcastMessage. Se il metodo toBroadcast non esiste, verrà usato il metodo toArray per raccogliere i dati da trasmettere. I dati restituiti saranno codificati in JSON e trasmessi al tuo frontend basato su JavaScript. Vediamo un esempio di metodo toBroadcast:

    use Illuminate\Notifications\Messages\BroadcastMessage;

    /**
     * Get the broadcastable representation of the notification.
     */
    public function toBroadcast(object $notifiable): BroadcastMessage
    {
        return new BroadcastMessage([
            'invoice_id' => $this->invoice->id,
            'amount' => $this->invoice->amount,
        ]);
    }

Configurazione della Coda Broadcast

Tutte le notifiche broadcast vengono messe in coda per la trasmissione. Se desideri configurare la connessione della coda o il nome della coda utilizzati per l’operazione di broadcast, puoi usare i metodi onConnection e onQueue di BroadcastMessage:

return (new BroadcastMessage($data))
                ->onConnection('sqs')
                ->onQueue('broadcasts');

Personalizzare il Tipo di Notifica

Oltre ai dati che specifichi, tutte le notifiche broadcast includono anche un campo type che contiene il nome completo della classe della notifica. Se desideri personalizzare il type della notifica, puoi definire un metodo broadcastType nella classe della notifica:

/**
 * Ottieni il tipo della notifica che viene trasmessa.
 */
public function broadcastType(): string
{
    return 'broadcast.message';
}

Ascoltare le Notifiche

Le notifiche verranno trasmesse su un canale privato formattato utilizzando la convenzione {notifiable}.{id}. Quindi, se stai inviando una notifica a un’istanza di App\Models\User con un ID di 1, la notifica sarà trasmessa sul canale privato App.Models.User.1. Quando usi Laravel Echo, puoi facilmente ascoltare le notifiche su un canale utilizzando il metodo notification:

    Echo.private('App.Models.User.' + userId)
        .notification((notification) => {
            console.log(notification.type);
        });

Personalizzare il Canale di Notifica

Se desideri personalizzare il canale su cui vengono trasmesse le notifiche broadcast di un’entità, puoi definire un metodo receivesBroadcastNotificationsOn sull’entità notificabile:

<?php

namespace App\Models;

use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * I canali sui quali l'utente riceve le notifiche broadcast.
     */
    public function receivesBroadcastNotificationsOn(): string
    {
        return 'users.'.$this->id;
    }
}

Notifiche SMS

Prerequisiti

L’invio di notifiche SMS in Laravel è gestito da Vonage (precedentemente Nexmo). Prima di poter inviare notifiche tramite Vonage, devi installare i pacchetti laravel/vonage-notification-channel e guzzlehttp/guzzle:

    composer require laravel/vonage-notification-channel guzzlehttp/guzzle

Il pacchetto include un file di configurazione. Tuttavia, non è necessario esportare questo file di configurazione nella tua applicazione. Puoi semplicemente utilizzare le variabili d’ambiente VONAGE_KEY e VONAGE_SECRET per definire le tue chiavi pubblica e segreta di Vonage.

Dopo aver definito le tue chiavi, dovresti impostare una variabile d’ambiente VONAGE_SMS_FROM che definisce il numero di telefono da cui verranno inviati i tuoi messaggi SMS per impostazione predefinita. Puoi generare questo numero di telefono all’interno del pannello di controllo Vonage:

    VONAGE_SMS_FROM=15556666666

Formattazione delle Notifiche SMS

Se una notifica può essere inviata come SMS, dovresti definire un metodo toVonage nella classe della notifica. Questo metodo riceverà un’entità $notifiable e dovrebbe restituire un’istanza di Illuminate\Notifications\Messages\VonageMessage:

use Illuminate\Notifications\Messages\VonageMessage;

/**
 * Ottieni la rappresentazione Vonage / SMS della notifica.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
                ->content('Il contenuto del tuo messaggio SMS');
}

Contenuto Unicode

Se il tuo messaggio SMS contiene caratteri unicode, dovresti chiamare il metodo unicode durante la creazione dell’istanza di VonageMessage:

use Illuminate\Notifications\Messages\VonageMessage;

/**
 * Ottieni la rappresentazione Vonage / SMS della notifica.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
                ->content('Il tuo messaggio unicode')
                ->unicode();
}

Personalizzare il numero "Da"

Se desideri inviare alcune notifiche da un numero di telefono diverso da quello specificato nella tua variabile d’ambiente VONAGE_SMS_FROM, puoi chiamare il metodo from su un’istanza di VonageMessage:

use Illuminate\Notifications\Messages\VonageMessage;

/**
 * Ottieni la rappresentazione Vonage / SMS della notifica.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
                ->content('Contenuto del tuo messaggio SMS')
                ->from('15554443333');
}

Aggiungere un Riferimento Cliente

Se desideri tenere traccia dei costi per utente, team o cliente, puoi aggiungere un "riferimento cliente" alla notifica. Vonage ti permetterà di generare report utilizzando questo riferimento cliente in modo da comprendere meglio l’utilizzo degli SMS da parte di un determinato cliente. Il riferimento cliente può essere qualsiasi stringa fino a 40 caratteri:

use Illuminate\Notifications\Messages\VonageMessage;

/**
 * Ottieni la rappresentazione Vonage / SMS della notifica.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
                ->clientReference((string) $notifiable->id)
                ->content('Il contenuto del tuo messaggio SMS');
}

Inoltro delle Notifiche SMS

Per inoltrare le notifiche Vonage al numero di telefono corretto, definisci un metodo routeNotificationForVonage nella tua entità notificabile:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Illuminate\Notifications\Notification;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Inoltra le notifiche per il canale Vonage.
     */
    public function routeNotificationForVonage(Notification $notification): string
    {
        return $this->phone_number;
    }
}

Notifiche Slack

Prerequisiti

Prima di inviare notifiche Slack, dovresti installare il canale di notifica Slack tramite Composer:

composer require laravel/slack-notification-channel

Inoltre, devi creare una Slack App per il tuo workspace Slack.

Se devi inviare notifiche solo nello stesso workspace Slack in cui è creata l’App, assicurati che la tua App abbia gli scopes chat:write, chat:write.public e chat:write.customize. Se vuoi inviare messaggi come la tua Slack App, assicurati che la tua App abbia anche lo scope chat:write:bot. Questi scopes possono essere aggiunti dalla scheda di gestione App "OAuth & Permissions" all’interno di Slack.

Successivamente, copia il "Bot User OAuth Token" dell’App e inseriscilo nell’array di configurazione slack nel file di configurazione services.php della tua applicazione. Questo token si trova nella scheda "OAuth & Permissions" all’interno di Slack:

    'slack' => [
        'notifications' => [
            'bot_user_oauth_token' => env('SLACK_BOT_USER_OAUTH_TOKEN'),
            'channel' => env('SLACK_BOT_USER_DEFAULT_CHANNEL'),
        ],
    ],

Distribuzione dell’App

Se la tua applicazione invierà notifiche a workspace Slack esterni appartenenti agli utenti della tua applicazione, dovrai "distribuire" la tua App tramite Slack. La distribuzione dell’App può essere gestita dalla scheda "Gestisci Distribuzione" della tua App all’interno di Slack. Una volta che la tua App è stata distribuita, puoi usare Socialite per ottenere i token Bot di Slack per conto degli utenti della tua applicazione.

Formattazione delle Notifiche Slack

Se una notifica può essere inviata come messaggio Slack, dovresti definire un metodo toSlack nella classe della notifica. Questo metodo riceverà un’entità $notifiable e dovrebbe restituire un’istanza di Illuminate\Notifications\Slack\SlackMessage. Puoi creare notifiche ricche utilizzando l’API Block Kit di Slack. Il seguente esempio può essere visualizzato nel Block Kit builder di Slack:

    use Illuminate\Notifications\Slack\BlockKit\Blocks\ContextBlock;
    use Illuminate\Notifications\Slack\BlockKit\Blocks\SectionBlock;
    use Illuminate\Notifications\Slack\BlockKit\Composites\ConfirmObject;
    use Illuminate\Notifications\Slack\SlackMessage;

    /**
     * Get the Slack representation of the notification.
     */
    public function toSlack(object $notifiable): SlackMessage
    {
        return (new SlackMessage)
                ->text('One of your invoices has been paid!')
                ->headerBlock('Invoice Paid')
                ->contextBlock(function (ContextBlock $block) {
                    $block->text('Customer #1234');
                })
                ->sectionBlock(function (SectionBlock $block) {
                    $block->text('An invoice has been paid.');
                    $block->field("*Invoice No:*\n1000")->markdown();
                    $block->field("*Invoice Recipient:*\ntaylor@laravel.com")->markdown();
                })
                ->dividerBlock()
                ->sectionBlock(function (SectionBlock $block) {
                    $block->text('Congratulations!');
                });
    }

Utilizzo del Template di Block Kit Builder di Slack

Invece di usare i metodi fluenti del message builder per creare il tuo messaggio Block Kit, puoi fornire il payload JSON grezzo generato da Block Kit Builder di Slack al metodo usingBlockKitTemplate:

use Illuminate\Notifications\Slack\SlackMessage;
use Illuminate\Support\Str;

/**
 * Ottieni la rappresentazione Slack della notifica.
 */
public function toSlack(object $notifiable): SlackMessage
{
    $template = <<<JSON
        {
          "blocks": [
            {
              "type": "header",
              "text": {
                "type": "plain_text",
                "text": "Annuncio del Team"
              }
            }, 
            {
              "type": "section",
              "text": {
                "type": "plain_text",
                "text": "Stiamo assumendo!"
              }
            }
          ]
        }
    JSON;

    return (new SlackMessage)
            ->usingBlockKitTemplate($template);
}

Interattività di Slack

Il sistema di notifiche Block Kit di Slack offre potenti funzionalità per gestire l’interazione degli utenti. Per utilizzare queste funzionalità, la tua App Slack deve avere abilitata l’"Interattività" e configurata una "Request URL" che punti a un URL servito dalla tua applicazione. Queste impostazioni possono essere gestite dalla scheda di gestione App "Interattività e Scorciatoie" all’interno di Slack.

Nell’esempio seguente, che utilizza il metodo actionsBlock, Slack invierà una richiesta POST alla tua "Request URL" con un payload contenente l’utente Slack che ha cliccato il bottone, l’ID del bottone cliccato e altro ancora. La tua applicazione può quindi determinare l’azione da intraprendere basandosi sul payload. Dovresti anche verificare la richiesta sia stata fatta da Slack:

use Illuminate\Notifications\Slack\BlockKit\Blocks\ActionsBlock;
use Illuminate\Notifications\Slack\BlockKit\Blocks\ContextBlock;
use Illuminate\Notifications\Slack\BlockKit\Blocks\SectionBlock;
use Illuminate\Notifications\Slack\SlackMessage;

/**
 * Get the Slack representation of the notification.
 */
public function toSlack(object $notifiable): SlackMessage
{
    return (new SlackMessage)
            ->text('One of your invoices has been paid!')
            ->headerBlock('Invoice Paid')
            ->contextBlock(function (ContextBlock $block) {
                $block->text('Customer #1234');
            })
            ->sectionBlock(function (SectionBlock $block) {
                $block->text('An invoice has been paid.');
            })
            ->actionsBlock(function (ActionsBlock $block) {
                 // ID defaults to "button_acknowledge_invoice"...
                $block->button('Acknowledge Invoice')->primary();

                // Manually configure the ID...
                $block->button('Deny')->danger()->id('deny_invoice');
            });
}

Modali di Conferma

Se vuoi che gli utenti confermino un’azione prima che venga eseguita, puoi utilizzare il metodo confirm quando definisci il tuo pulsante. Il metodo confirm accetta un messaggio e una closure che riceve un’istanza di ConfirmObject:

use Illuminate\Notifications\Slack\BlockKit\Blocks\ActionsBlock;
use Illuminate\Notifications\Slack\BlockKit\Blocks\ContextBlock;
use Illuminate\Notifications\Slack\BlockKit\Blocks\SectionBlock;
use Illuminate\Notifications\Slack\BlockKit\Composites\ConfirmObject;
use Illuminate\Notifications\Slack\SlackMessage;

/**
 * Ottieni la rappresentazione Slack della notifica.
 */
public function toSlack(object $notifiable): SlackMessage
{
    return (new SlackMessage)
            ->text('One of your invoices has been paid!')
            ->headerBlock('Invoice Paid')
            ->contextBlock(function (ContextBlock $block) {
                $block->text('Customer #1234');
            })
            ->sectionBlock(function (SectionBlock $block) {
                $block->text('An invoice has been paid.');
            })
            ->actionsBlock(function (ActionsBlock $block) {
                $block->button('Acknowledge Invoice')
                    ->primary()
                    ->confirm(
                        'Acknowledge the payment and send a thank you email?',
                        function (ConfirmObject $dialog) {
                            $dialog->confirm('Yes');
                            $dialog->deny('No');
                        }
                    );
            });
}

Ispezionare i Blocchi di Slack

Se vuoi ispezionare rapidamente i blocchi che hai creato, puoi chiamare il metodo dd sull’istanza SlackMessage. Il metodo dd genererà e mostrerà un URL al Block Kit Builder di Slack, che mostra un’anteprima del payload e della notifica nel tuo browser. Puoi passare true al metodo dd per mostrare il payload grezzo:

return (new SlackMessage)
        ->text('One of your invoices has been paid!')
        ->headerBlock('Invoice Paid')
        ->dd();

Instradamento delle Notifiche Slack

Per indirizzare le notifiche Slack al team e al canale Slack appropriati, definisci un metodo routeNotificationForSlack sul tuo modello notificabile. Questo metodo può restituire uno dei tre valori:

• null – che rinvia l’instradamento al canale configurato nella notifica stessa. Puoi usare il metodo to durante la costruzione del tuo SlackMessage per configurare il canale all’interno della notifica.
• Una stringa che specifica il canale Slack a cui inviare la notifica, ad esempio #support-channel.
• Un’istanza di SlackRoute, che ti permette di specificare un token OAuth e il nome del canale, ad esempio SlackRoute::make($this->slack_channel, $this->slack_token). Questo metodo dovrebbe essere usato per inviare notifiche a spazi di lavoro esterni.

Per esempio, restituire #support-channel dal metodo routeNotificationForSlack invierà la notifica al canale #support-channel nello spazio di lavoro associato al token OAuth dell’utente Bot situato nel file di configurazione services.php della tua applicazione:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Illuminate\Notifications\Notification;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Instrada le notifiche per il canale Slack.
     */
    public function routeNotificationForSlack(Notification $notification): mixed
    {
        return '#support-channel';
    }
}

Notificare Workspace Slack Esterne

Prima di inviare notifiche a workspace Slack esterne, la tua Slack App deve essere distribuita.

Spesso vorrai inviare notifiche ai workspace Slack dei tuoi utenti. Per fare ciò, devi prima ottenere un token OAuth di Slack per l’utente. Fortunatamente, Laravel Socialite include un driver Slack che ti permette di autenticare facilmente gli utenti della tua applicazione con Slack e ottenere un token bot.

Una volta ottenuto il token bot e salvato nel database della tua applicazione, puoi utilizzare il metodo SlackRoute::make per indirizzare una notifica al workspace dell’utente. Inoltre, la tua applicazione probabilmente dovrà offrire agli utenti la possibilità di specificare a quale canale inviare le notifiche:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Illuminate\Notifications\Notification;
use Illuminate\Notifications\Slack\SlackRoute;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Instrada le notifiche per il canale Slack.
     */
    public function routeNotificationForSlack(Notification $notification): mixed
    {
        return SlackRoute::make($this->slack_channel, $this->slack_token);
    }
}

Localizzazione delle notifiche

Laravel permette di inviare notifiche in una locale diversa da quella attuale della richiesta HTTP, e ricorderà questa locale anche se la notifica è in coda.

Per fare ciò, la classe Illuminate\Notifications\Notification offre un metodo locale per impostare la lingua desiderata. L’applicazione passerà a questa locale quando la notifica viene valutata e tornerà alla locale precedente al termine della valutazione:

    $user->notify((new InvoicePaid($invoice))->locale('es'));

La localizzazione di più entità notificabili può essere ottenuta anche tramite la facade Notification:

    Notification::locale('es')->send(
        $users, new InvoicePaid($invoice)
    );

Lingua dell’Utente

A volte, le applicazioni memorizzano la lingua preferita di ogni utente. Implementando il contratto HasLocalePreference sul tuo modello notificabile, puoi istruire Laravel a usare la lingua memorizzata quando invia una notifica:

use Illuminate\Contracts\Translation\HasLocalePreference;

class User extends Model implements HasLocalePreference
{
    /**
     * Ottiene la locale preferita dell'utente.
     */
    public function preferredLocale(): string
    {
        return $this->locale;
    }
}

Una volta implementata l’interfaccia, Laravel userà automaticamente la lingua preferita quando invia notifiche e mailables al modello. Pertanto, non è necessario chiamare il metodo locale quando usi questa interfaccia:

$user->notify(new InvoicePaid($invoice));

Test

Puoi usare il metodo fake della facade Notification per impedire l’invio delle notifiche. Tipicamente, l’invio delle notifiche non è correlato al codice che stai testando. Molto probabilmente, è sufficiente semplicemente asserire che Laravel è stato istruito di inviare una determinata notifica.

Dopo aver chiamato il metodo fake della facade Notification, puoi quindi asserire che le notifiche sono state indirizzate agli utenti e persino esaminare i dati che le notifiche hanno ricevuto:

<?php

use App\Notifications\OrderShipped;
use Illuminate\Support\Facades\Notification;

test('orders can be shipped', function () {
    Notification::fake();

    // Esegui la spedizione dell'ordine...

    // Verifica che nessuna notifica sia stata inviata...
    Notification::assertNothingSent();

    // Verifica che una notifica sia stata inviata agli utenti indicati...
    Notification::assertSentTo(
        [$user], OrderShipped::class
    );

    // Verifica che una notifica non sia stata inviata...
    Notification::assertNotSentTo(
        [$user], AnotherNotification::class
    );

    // Verifica che sia stato inviato un determinato numero di notifiche...
    Notification::assertCount(3);
});

<?php

namespace Tests\Feature;

use App\Notifications\OrderShipped;
use Illuminate\Support\Facades\Notification;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_orders_can_be_shipped(): void
    {
        Notification::fake();

        // Esegui la spedizione dell'ordine...

        // Verifica che nessuna notifica sia stata inviata...
        Notification::assertNothingSent();

        // Verifica che una notifica sia stata inviata agli utenti indicati...
        Notification::assertSentTo(
            [$user], OrderShipped::class
        );

        // Verifica che una notifica non sia stata inviata...
        Notification::assertNotSentTo(
            [$user], AnotherNotification::class
        );

        // Verifica che sia stato inviato un determinato numero di notifiche...
        Notification::assertCount(3);
    }
}

Puoi passare una closure ai metodi assertSentTo o assertNotSentTo per asserire che una notifica sia stata inviata e che superi un dato "test di verità". Se almeno una notifica viene inviata e supera il test di verità, l’asserzione avrà successo:

Notification::assertSentTo(
    $user,
    function (OrderShipped $notification, array $channels) use ($order) {
        return $notification->order->id === $order->id;
    }
);

Notifiche On-Demand

Se il codice che stai testando invia notifiche on-demand, puoi verificare che la notifica on-demand sia stata inviata usando il metodo assertSentOnDemand:

Notification::assertSentOnDemand(OrderShipped::class);

Passando una closure come secondo argomento al metodo assertSentOnDemand, puoi determinare se una notifica on-demand è stata inviata all’indirizzo "route" corretto:

Notification::assertSentOnDemand(
    OrderShipped::class,
    function (OrderShipped $notification, array $channels, object $notifiable) use ($user) {
        return $notifiable->routes['mail'] === $user->email;
    }
);

Eventi di Notifica

Evento di Invio Notifica

Quando viene inviata una notifica, il sistema delle notifiche emette l’evento Illuminate\Notifications\Events\NotificationSending. Questo include l’entità "notificabile" e l’istanza della notifica stessa. Puoi creare listener per eventi per questo evento nella tua applicazione:

use Illuminate\Notifications\Events\NotificationSending;

class CheckNotificationStatus
{
    /**
     * Gestisci l'evento.
     */
    public function handle(NotificationSending $event): void
    {
        // ...
    }
}

La notifica non verrà inviata se un listener per l’evento NotificationSending restituisce false dal suo metodo handle:

/**
 * Gestisci l'evento.
 */
public function handle(NotificationSending $event): bool
{
    return false;
}

All’interno di un listener per eventi, puoi accedere alle proprietà notifiable, notification e channel dell’evento per conoscere meglio il destinatario della notifica o la notifica stessa:

/**
 * Gestisci l'evento.
 */
public function handle(NotificationSending $event): void
{
    // $event->channel
    // $event->notifiable
    // $event->notification
}

Evento di Notifica Inviata

Quando una notifica viene inviata, il evento Illuminate\Notifications\Events\NotificationSent viene emesso dal sistema di notifiche. Questo include l’entità "notifiable" e l’istanza della notifica stessa. Puoi creare ascoltatori di eventi per questo evento nella tua applicazione:

use Illuminate\Notifications\Events\NotificationSent;

class LogNotification
{
    /**
     * Gestisci l'evento dato.
     */
    public function handle(NotificationSent $event): void
    {
        // ...
    }
}

All’interno di un ascoltatore di eventi, puoi accedere alle proprietà notifiable, notification, channel e response sull’evento per conoscere meglio il destinatario della notifica o la notifica stessa:

/**
 * Gestisci l'evento dato.
 */
public function handle(NotificationSent $event): void
{
    // $event->channel
    // $event->notifiable
    // $event->notification
    // $event->response
}

Canali Personalizzati

Laravel viene fornito con diversi canali di notifica, ma potresti voler scrivere i tuoi driver per inviare notifiche tramite altri canali. Laravel lo rende semplice. Per iniziare, definisci una classe che contiene un metodo send. Il metodo dovrebbe ricevere due argomenti: un $notifiable e una $notification.

All’interno del metodo send, puoi chiamare metodi sulla notifica per recuperare un oggetto messaggio compreso dal tuo canale e poi inviare la notifica all’istanza $notifiable come preferisci:

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;

class VoiceChannel
{
    /**
     * Invia la notifica data.
     */
    public function send(object $notifiable, Notification $notification): void
    {
        $message = $notification->toVoice($notifiable);

        // Invia la notifica all'istanza $notifiable...
    }
}

Una volta definita la classe del tuo canale di notifica, puoi restituire il nome della classe dal metodo via di qualsiasi delle tue notifiche. In questo esempio, il metodo toVoice della tua notifica può restituire qualsiasi oggetto tu scelga per rappresentare i messaggi vocali. Ad esempio, potresti definire la tua classe VoiceMessage per rappresentare questi messaggi:

<?php

namespace App\Notifications;

use App\Notifications\Messages\VoiceMessage;
use App\Notifications\VoiceChannel;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification
{
    use Queueable;

    /**
     * Ottieni i canali di notifica.
     */
    public function via(object $notifiable): string
    {
        return VoiceChannel::class;
    }

    /**
     * Ottieni la rappresentazione vocale della notifica.
     */
    public function toVoice(object $notifiable): VoiceMessage
    {
        // ...
    }
}