Laravel документація українською

Сповіщення

Вступ

На додаток до підтримки відправки електронної пошти, Laravel надає підтримку для відправки сповіщень через різноманітні канали доставки, включаючи електронну пошту, SMS (через Vonage, раніше відомий як Nexmo), та Slack. Крім того, було створено різноманітні спільнотою створені канали сповіщень, які дозволяють відправляти сповіщення через десятки різних каналів! Сповіщення також можуть зберігатися в базі даних, щоб їх можна було відображати у вашому веб-інтерфейсі.

Зазвичай, сповіщення повинні бути короткими інформаційними повідомленнями, які повідомляють користувачів про щось, що сталося у вашому застосунку. Наприклад, якщо ви пишете білінговий застосунок, ви можете надіслати сповіщення "Рахунок оплачено" вашим користувачам через канали електронної пошти та SMS.

Генерація Сповіщень

У Laravel кожне сповіщення представлено окремим класом, який зазвичай зберігається в директорії app/Notifications. Не хвилюйтеся, якщо ви не бачите цю директорію у вашому застосунку - вона буде створена для вас, коли ви виконаєте команду Artisan make:notification:

php artisan make:notification InvoicePaid

This команда розмістить новий клас сповіщення у вашому каталозі app/Notifications. Кожен клас сповіщення містить метод via та змінну кількість методів побудови повідомлень, таких як toMail або toDatabase, які перетворюють сповіщення на повідомлення, пристосоване для цього конкретного каналу.

Надсилання сповіщень

Використання трейту Notifiable

Сповіщення можуть бути надіслані двома способами: використовуючи метод notify трейту Notifiable або використовуючи Notification фасад. Трейт Notifiable включений у модель App\Models\User вашого застосунку за замовчуванням:

<?php
 
namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
 
class User extends Authenticatable
{
    use Notifiable;
}

Метод notify, який надається цим трейтом, очікує отримати екземпляр сповіщення:

use App\Notifications\InvoicePaid;
 
$user->notify(new InvoicePaid($invoice));

Пам'ятайте, ви можете використовувати трейт Notifiable у будь-якій з ваших моделей. Ви не обмежені лише включенням його у вашу модель User.

Використання фасаду Notification

Альтернативно, ви можете відправляти сповіщення через Notification фасад. Цей підхід корисний, коли вам потрібно відправити сповіщення до декількох об'єктів, що можуть отримувати сповіщення, таких як колекція користувачів. Щоб відправити сповіщення, використовуючи фасад, передайте всі об'єкти, що можуть отримувати сповіщення, та екземпляр сповіщення до методу send:

use Illuminate\Support\Facades\Notification;
 
Notification::send($users, new InvoicePaid($invoice));

Ви також можете надіслати сповіщення негайно, використовуючи метод sendNow. Цей метод надішле сповіщення негайно, навіть якщо сповіщення реалізує інтерфейс ShouldQueue:

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

Вказання Каналів Доставки

Кожен клас сповіщень має метод via, який визначає, через які канали буде доставлено сповіщення. Сповіщення можуть бути надіслані через канали mail, database, broadcast, vonage та slack.

Якщо ви хочете використовувати інші канали доставки, такі як Telegram або Pusher, відвідайте сайт, керований спільнотою, Laravel Notification Channels.

Метод via отримує екземпляр $notifiable, який буде екземпляром класу, до якого надсилається сповіщення. Ви можете використовувати $notifiable, щоб визначити, через які канали має бути доставлено сповіщення:

/**
 * Отримати канали доставки сповіщення.
 *
 * @return array<int, string>
 */
public function via(object $notifiable): array
{
    return $notifiable->prefers_sms ? ['vonage'] : ['mail', 'database'];
}

Черга сповіщень

Перш ніж поставити сповіщення в чергу, ви повинні налаштувати свою чергу і запустити worker.

Відправка сповіщень може зайняти час, особливо якщо канал потребує виконання зовнішнього API виклику для доставки сповіщення. Щоб прискорити час відгуку вашого застосунку, дозвольте вашим сповіщенням бути поставленими в чергу, додавши інтерфейс ShouldQueue та трейт Queueable до вашого класу. Інтерфейс та трейт вже імпортовані для всіх сповіщень, згенерованих за допомогою команди make:notification, тому ви можете одразу додати їх до вашого класу сповіщень:

<?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;
 
    // ...
}

Після того, як інтерфейс ShouldQueue було додано до вашого сповіщення, ви можете відправити сповіщення як зазвичай. Laravel виявить інтерфейс ShouldQueue у класі та автоматично поставить доставку сповіщення в чергу:

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

Коли сповіщення ставляться в чергу, для кожної комбінації одержувача та каналу буде створено завдання в черзі. Наприклад, шість завдань буде відправлено в чергу, якщо ваше сповіщення має трьох одержувачів і два канали.

Відтермінування сповіщень

Якщо ви хочете відкласти доставку сповіщення, ви можете додати метод delay до створення вашого сповіщення:

$delay = now()->addMinutes(10);
 
$user->notify((new InvoicePaid($invoice))->delay($delay));

Ви можете передати масив до методу delay, щоб вказати тривалість затримки для конкретних каналів:

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

Альтернативно, ви можете визначити метод withDelay безпосередньо в класі сповіщення. Метод withDelay повинен повертати масив з назвами каналів та значеннями затримки:

/**
 * Визначте затримку доставки сповіщення.
 *
 * @return array<string, \Illuminate\Support\Carbon>
 */
public function withDelay(object $notifiable): array
{
    return [
        'mail' => now()->addMinutes(5),
        'sms' => now()->addMinutes(10),
    ];
}

Налаштування з'єднання черги для сповіщень

За замовчуванням, відкладені сповіщення будуть поставлені в чергу, використовуючи з'єднання черги за замовчуванням вашого застосунку. Якщо ви хочете вказати інше з'єднання, яке слід використовувати для конкретного сповіщення, ви можете викликати метод onConnection з конструктора вашого сповіщення:

<?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;
 
    /**
     * Створити новий екземпляр сповіщення.
     */
    public function __construct()
    {
        $this->onConnection('redis');
    }
}

Або, якщо ви хочете вказати конкретне з'єднання черги, яке слід використовувати для кожного каналу сповіщень, підтримуваного сповіщенням, ви можете визначити метод viaConnections у вашому сповіщенні. Цей метод повинен повертати масив пар імен каналів / імен з'єднань черги:

/**
 * Визначте, які з'єднання слід використовувати для кожного каналу сповіщень.
 *
 * @return array<string, string>
 */
public function viaConnections(): array
{
    return [
        'mail' => 'redis',
        'database' => 'sync',
    ];
}

Налаштування черг каналу сповіщень

Якщо ви хочете вказати конкретну чергу, яка повинна використовуватися для кожного каналу сповіщень, підтримуваного сповіщенням, ви можете визначити метод viaQueues у вашому сповіщенні. Цей метод повинен повертати масив пар назва каналу / назва черги:

/**
 * Визначте, які черги слід використовувати для кожного каналу сповіщень.
 *
 * @return array<string, string>
 */
public function viaQueues(): array
{
    return [
        'mail' => 'mail-queue',
        'slack' => 'slack-queue',
    ];
}

Черга Повідомлень Middleware

Сповіщення в черзі можуть визначати middleware так само, як і завдання в черзі. Щоб почати, визначте метод middleware у вашому класі сповіщення. Метод middleware отримає змінні $notifiable та $channel, які дозволяють налаштувати повернене middleware на основі місця призначення сповіщення:

use Illuminate\Queue\Middleware\RateLimited;
 
/**
 * Отримати middleware, через яке має пройти завдання сповіщення.
 *
 * @return array<int, object>
 */
public function middleware(object $notifiable, string $channel)
{
    return match ($channel) {
        'mail' => [new RateLimited('postmark')],
        'slack' => [new RateLimited('slack')],
        default => [],
    };
}

Чергові Сповіщення та Транзакції Бази Даних

Коли поставлені в чергу сповіщення відправляються в межах транзакцій бази даних, вони можуть бути оброблені чергою до того, як транзакція бази даних буде зафіксована. Коли це відбувається, будь-які оновлення, які ви зробили в моделях або записах бази даних під час транзакції, можуть ще не відображатися в базі даних. Крім того, будь-які моделі або записи бази даних, створені в межах транзакції, можуть не існувати в базі даних. Якщо ваше сповіщення залежить від цих моделей, можуть виникнути несподівані помилки, коли завдання, яке відправляє поставлене в чергу сповіщення, буде оброблено.

Якщо параметр конфігурації after_commit вашого з'єднання черги встановлено на false, ви все ще можете вказати, що певне сповіщення в черзі має бути відправлено після того, як всі відкриті транзакції бази даних будуть зафіксовані, викликавши метод afterCommit під час відправлення сповіщення:

use App\Notifications\InvoicePaid;
 
$user->notify((new InvoicePaid($invoice))->afterCommit());

Альтернативно, ви можете викликати метод afterCommit з конструктора вашого сповіщення:

<?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;
 
    /**
     * Створити новий екземпляр сповіщення.
     */
    public function __construct()
    {
        $this->afterCommit();
    }
}

Щоб дізнатися більше про вирішення цих проблем, перегляньте документацію щодо чергованих завдань і транзакцій бази даних.

Визначення, чи слід надсилати поставлене в чергу сповіщення

Після того як поставлене в чергу сповіщення було відправлено в чергу для обробки у фоновому режимі, воно зазвичай приймається працівником черги і відправляється до свого призначеного отримувача.

Однак, якщо ви хочете прийняти остаточне рішення щодо того, чи слід надсилати поставлене в чергу сповіщення після його обробки робітником черги, ви можете визначити метод shouldSend у класі сповіщення. Якщо цей метод повертає false, сповіщення не буде надіслано:

/**
 * Визначте, чи слід надсилати сповіщення.
 */
public function shouldSend(object $notifiable, string $channel): bool
{
    return $this->invoice->isPaid();
}

Сповіщення на вимогу

Іноді вам може знадобитися надіслати сповіщення комусь, хто не зберігається як "користувач" вашого застосунку. Використовуючи метод route фасаду Notification, ви можете вказати інформацію про маршрутизацію сповіщення перед його відправкою:

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));

Якщо ви хочете вказати ім'я одержувача при відправленні on-demand сповіщення на маршрут mail, ви можете надати масив, що містить адресу електронної пошти як ключ і ім'я як значення першого елемента в масиві:

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

Використовуючи метод routes, ви можете надати інформацію про маршрутизацію для декількох каналів сповіщень одночасно:

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

Сповіщення електронною поштою

Форматування Поштових Повідомлень

Якщо сповіщення підтримує відправку електронною поштою, ви повинні визначити метод toMail у класі сповіщення. Цей метод отримає сутність $notifiable і повинен повернути екземпляр Illuminate\Notifications\Messages\MailMessage.

Клас MailMessage містить кілька простих методів, які допоможуть вам створювати транзакційні електронні повідомлення. Поштові повідомлення можуть містити рядки тексту, а також "заклик до дії". Давайте розглянемо приклад методу toMail:

/**
 * Отримати поштове представлення сповіщення.
 */
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!');
}

Зверніть увагу, що ми використовуємо $this->invoice->id у нашому методі toMail. Ви можете передати будь-які дані, які потрібні вашому сповіщенню для створення його повідомлення, у конструктор сповіщення.

У цьому прикладі ми реєструємо привітання, рядок тексту, заклик до дії, а потім ще один рядок тексту. Ці методи, надані об'єктом MailMessage, роблять форматування невеликих транзакційних електронних листів простим і швидким. Поштовий канал потім перетворить компоненти повідомлення у красивий, адаптивний HTML шаблон електронної пошти з текстовим аналогом. Ось приклад електронного листа, згенерованого каналом mail:

Коли надсилаєте поштові сповіщення, обов'язково встановіть параметр конфігурації name у вашому конфігураційному файлі config/app.php. Це значення буде використовуватися в заголовку та нижньому колонтитулі ваших поштових сповіщень.

Повідомлення про помилки

Деякі сповіщення інформують користувачів про помилки, такі як невдала оплата рахунку. Ви можете вказати, що поштове повідомлення стосується помилки, викликавши метод error під час створення вашого повідомлення. При використанні методу error у поштовому повідомленні, кнопка заклику до дії буде червоною замість чорної:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->error()
        ->subject('Invoice Payment Failed')
        ->line('...');
}

Інші параметри форматування поштових сповіщень

Замість визначення "рядків" тексту в класі сповіщення, ви можете використовувати метод view для вказівки користувацького шаблону, який слід використовувати для рендерингу електронного листа сповіщення:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)->view(
        'mail.invoice.paid', ['invoice' => $this->invoice]
    );
}

Ви можете вказати представлення у вигляді звичайного тексту для поштового повідомлення, передавши ім'я представлення як другий елемент масиву, який передається методу view:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)->view(
        ['mail.invoice.paid', 'mail.invoice.paid-text'],
        ['invoice' => $this->invoice]
    );
}

Або, якщо ваше повідомлення має лише текстове представлення, ви можете скористатися методом text:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)->text(
        'mail.invoice.paid-text', ['invoice' => $this->invoice]
    );
}

Налаштування Відправника

За замовчуванням адреса відправника електронної пошти визначається у файлі конфігурації config/mail.php. Однак, ви можете вказати адресу відправника для конкретного сповіщення, використовуючи метод from:

/**
 * Отримати представлення сповіщення у вигляді листа.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->from('barrett@example.com', 'Barrett Blair')
        ->line('...');
}

Налаштування Одержувача

Коли надсилаються сповіщення через канал mail, система сповіщень автоматично шукатиме властивість email у вашій сутності, що може бути сповіщена. Ви можете налаштувати, яка адреса електронної пошти буде використовуватися для доставки сповіщення, визначивши метод routeNotificationForMail у сутності, що може бути сповіщена:

<?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;
 
    /**
     * Маршрутизація сповіщень для каналу пошти.
     *
     * @return  array<string, string>|string
     */
    public function routeNotificationForMail(Notification $notification): array|string
    {
        // Повернути лише адресу електронної пошти...
        return $this->email_address;
 
        // Повернути адресу електронної пошти та ім'я...
        return [$this->email_address => $this->name];
    }
}

Налаштування Теми

За замовчуванням, тема електронного листа - це назва класу сповіщення, відформатована у "Заголовний Регістр". Отже, якщо ваш клас сповіщення називається InvoicePaid, тема електронного листа буде Invoice Paid. Якщо ви хочете вказати іншу тему для повідомлення, ви можете викликати метод subject при створенні вашого повідомлення:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->subject('Notification Subject')
        ->line('...');
}

Налаштування Mailer

За замовчуванням, сповіщення електронною поштою буде надіслано з використанням стандартного поштового сервісу, визначеного у файлі конфігурації config/mail.php. Однак, ви можете вказати інший поштовий сервіс під час виконання, викликавши метод mailer при створенні вашого повідомлення:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->mailer('postmark')
        ->line('...');
}

Налаштування шаблонів

Ви можете змінити HTML та текстовий шаблон, що використовується для поштових сповіщень, опублікувавши ресурси пакету сповіщень. Після виконання цієї команди шаблони поштових сповіщень будуть розташовані в директорії resources/views/vendor/notifications:

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

Вкладення

Щоб додати вкладення до сповіщення електронної пошти, використовуйте метод attach під час створення вашого повідомлення. Метод attach приймає абсолютний шлях до файлу як свій перший аргумент:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->greeting('Hello!')
        ->attach('/path/to/file');
}

Метод attach, запропонований повідомленнями електронної пошти, також приймає об'єкти, що можуть бути прикріплені. Будь ласка, зверніться до всебічної документації щодо об'єктів, що можуть бути прикріплені, щоб дізнатися більше.

Коли ви додаєте файли до повідомлення, ви також можете вказати відображуване ім'я та / або MIME-тип, передавши array як другий аргумент до методу attach:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->greeting('Hello!')
        ->attach('/path/to/file', [
            'as' => 'name.pdf',
            'mime' => 'application/pdf',
        ]);
}

На відміну від прикріплення файлів у об'єктах для відправки пошти, ви не можете прикріпити файл безпосередньо з диска зберігання, використовуючи attachFromStorage. Натомість слід використовувати метод attach з абсолютним шляхом до файлу на диску зберігання. Альтернативно, ви можете повернути mailable з методу toMail:

use App\Mail\InvoicePaid as InvoicePaidMailable;
 
/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): Mailable
{
    return (new InvoicePaidMailable($this->invoice))
        ->to($notifiable->email)
        ->attachFromStorage('/path/to/file');
}

Коли це необхідно, до повідомлення можна прикріпити кілька файлів, використовуючи метод attachMany:

/**
 * Отримати поштове представлення сповіщення.
 */
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',
            ],
        ]);
}

Сирі дані вкладення

Метод attachData може бути використаний для прикріплення сирого рядка байтів як вкладення. Викликаючи метод attachData, ви повинні вказати ім'я файлу, яке має бути призначене вкладенню:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->greeting('Hello!')
        ->attachData($this->pdf, 'name.pdf', [
            'mime' => 'application/pdf',
        ]);
}

Додавання Тегів та Метаданих

Деякі сторонні постачальники електронної пошти, такі як Mailgun та Postmark, підтримують "теги" та "метадані" повідомлень, які можуть використовуватися для групування та відстеження електронних листів, надісланих вашим застосунком. Ви можете додати теги та метадані до електронного повідомлення за допомогою методів tag та metadata:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->greeting('Comment Upvoted!')
        ->tag('upvote')
        ->metadata('comment_id', $this->comment->id);
}

Якщо ваш застосунок використовує драйвер Mailgun, ви можете звернутися до документації Mailgun для отримання додаткової інформації про теги та метадані. Так само, можна звернутися до документації Postmark для отримання додаткової інформації про їх підтримку тегів та метаданих.

Якщо ваш застосунок використовує Amazon SES для відправки електронних листів, ви повинні використовувати метод metadata для прикріплення "тегів" SES до повідомлення.

Налаштування повідомлення Symfony

Метод withSymfonyMessage класу MailMessage дозволяє зареєструвати замикання, яке буде викликано з екземпляром Symfony Message перед відправкою повідомлення. Це дає вам можливість глибоко налаштувати повідомлення перед його доставкою:

use Symfony\Component\Mime\Email;
 
/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->withSymfonyMessage(function (Email $message) {
            $message->getHeaders()->addTextHeader(
                'Custom-Header', 'Header Value'
            );
        });
}

Використання Mailables

Якщо потрібно, ви можете повернути повний об'єкт mailable з методу toMail вашого сповіщення. Повертаючи Mailable замість MailMessage, вам потрібно буде вказати одержувача повідомлення, використовуючи метод to об'єкта mailable:

use App\Mail\InvoicePaid as InvoicePaidMailable;
use Illuminate\Mail\Mailable;
 
/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): Mailable
{
    return (new InvoicePaidMailable($this->invoice))
        ->to($notifiable->email);
}

Поштові повідомлення та сповіщення на вимогу

Якщо ви надсилаєте on-demand сповіщення, екземпляр $notifiable, переданий методу toMail, буде екземпляром Illuminate\Notifications\AnonymousNotifiable, який пропонує метод routeNotificationFor, що може бути використаний для отримання електронної адреси, на яку слід надіслати on-demand сповіщення:

use App\Mail\InvoicePaid as InvoicePaidMailable;
use Illuminate\Notifications\AnonymousNotifiable;
use Illuminate\Mail\Mailable;
 
/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): Mailable
{
    $address = $notifiable instanceof AnonymousNotifiable
        ? $notifiable->routeNotificationFor('mail')
        : $notifiable->email;
 
    return (new InvoicePaidMailable($this->invoice))
        ->to($address);
}

Попередній перегляд поштових сповіщень

Коли ви розробляєте шаблон поштового сповіщення, зручно швидко переглянути відображене поштове повідомлення у вашому браузері, як типовий шаблон Blade. З цієї причини Laravel дозволяє повернути будь-яке поштове повідомлення, згенероване поштовим сповіщенням, безпосередньо з замикання маршруту або контролера. Коли повертається MailMessage, воно буде відображено та показано у браузері, що дозволяє швидко переглянути його дизайн без необхідності відправляти його на фактичну електронну адресу:

use App\Models\Invoice;
use App\Notifications\InvoicePaid;
 
Route::get('/notification', function () {
    $invoice = Invoice::find(1);
 
    return (new InvoicePaid($invoice))
        ->toMail($invoice->user);
});

Сповіщення пошти Markdown

Markdown поштові сповіщення дозволяють скористатися попередньо створеними шаблонами поштових сповіщень, надаючи вам більше свободи для написання довших, налаштованих повідомлень. Оскільки повідомлення написані на Markdown, Laravel може відображати красиві, адаптивні HTML шаблони для повідомлень, а також автоматично генерувати текстову версію.

Генерація Повідомлення

Щоб згенерувати сповіщення з відповідним шаблоном Markdown, ви можете використовувати опцію --markdown команди Artisan make:notification:

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

Як і всі інші поштові сповіщення, сповіщення, що використовують шаблони Markdown, повинні визначати метод toMail у своєму класі сповіщень. Однак, замість використання методів line та action для побудови сповіщення, використовуйте метод markdown для вказівки назви шаблону Markdown, який слід використовувати. Масив даних, які ви хочете зробити доступними для шаблону, може бути переданий як другий аргумент методу:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    $url = url('/invoice/'.$this->invoice->id);
 
    return (new MailMessage)
        ->subject('Invoice Paid')
        ->markdown('mail.invoice.paid', ['url' => $url]);
}

Написання повідомлення

Markdown поштові сповіщення використовують комбінацію компонентів Blade та синтаксису Markdown, що дозволяє легко створювати сповіщення, використовуючи заздалегідь підготовлені компоненти сповіщень Laravel:

<x-mail::message>
# Рахунок оплачено
 
Ваш рахунок було оплачено!
 
<x-mail::button :url="$url">
Переглянути рахунок-фактуру
</x-mail::button>
 
Дякуємо,<br>
{{ config('app.name') }}
</x-mail::message>

Не використовуйте зайві відступи при написанні електронних листів у Markdown. Відповідно до стандартів Markdown, парсери Markdown будуть відображати вміст з відступами як блоки коду.

Компонент кнопки

Компонент кнопки відображає центроване посилання-кнопку. Компонент приймає два аргументи: url та необов'язковий color. Підтримувані кольори: primary, green та red. Ви можете додати стільки компонентів кнопок до сповіщення, скільки забажаєте:

<x-mail::button :url="$url" color="green">
Переглянути рахунок-фактуру
</x-mail::button>

Компонент панелі

Компонент панелі відображає заданий блок тексту в панелі, яка має трохи інший колір фону, ніж решта сповіщення. Це дозволяє привернути увагу до заданого блоку тексту:

<x-mail::panel>
Це вміст панелі.
</x-mail::panel>

Компонент Table

Компонент таблиці дозволяє перетворити таблицю Markdown у таблицю HTML. Компонент приймає таблицю Markdown як свій вміст. Вирівнювання стовпців таблиці підтримується за допомогою стандартного синтаксису вирівнювання таблиць Markdown:

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

Налаштування компонентів

Ви можете експортувати всі компоненти сповіщень у форматі Markdown до вашого власного застосунку для налаштування. Щоб експортувати компоненти, використовуйте команду Artisan vendor:publish для публікації тегу ресурсу laravel-mail:

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

Ця команда опублікує компоненти пошти Markdown у директорії resources/views/vendor/mail. Директорія mail міститиме директорії html та text, кожна з яких міститиме відповідні представлення кожного доступного компонента. Ви можете налаштовувати ці компоненти на свій розсуд.

Налаштування CSS

Після експорту компонентів, директорія resources/views/vendor/mail/html/themes міститиме файл default.css. Ви можете налаштувати CSS у цьому файлі, і ваші стилі автоматично будуть вбудовані в HTML-представлення ваших Markdown-сповіщень.

Якщо ви хочете створити абсолютно нову тему для Markdown компонентів Laravel, ви можете розмістити CSS файл у директорії html/themes. Після того, як ви назвете та збережете ваш CSS файл, оновіть опцію theme у конфігураційному файлі mail, щоб вона відповідала назві вашої нової теми.

Щоб налаштувати тему для окремого сповіщення, ви можете викликати метод theme під час створення поштового повідомлення сповіщення. Метод theme приймає назву теми, яка повинна бути використана при відправленні сповіщення:

/**
 * Отримати поштове представлення сповіщення.
 */
public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage)
        ->theme('invoice')
        ->subject('Invoice Paid')
        ->markdown('mail.invoice.paid', ['url' => $url]);
}

Сповіщення бази даних

Передумови

Канал сповіщень database зберігає інформацію про сповіщення в таблиці бази даних. Ця таблиця міститиме інформацію, таку як тип сповіщення, а також структуру даних JSON, яка описує сповіщення.

Ви можете виконати запит до таблиці, щоб відобразити сповіщення в інтерфейсі користувача вашого застосунку. Але перед тим, як ви зможете це зробити, вам потрібно створити таблицю бази даних для зберігання ваших сповіщень. Ви можете використати команду make:notifications-table, щоб згенерувати міграцію з відповідною схемою таблиці:

php artisan make:notifications-table
 
php artisan migrate

Якщо ваші моделі, що підлягають сповіщенню, використовують UUID або ULID як первинні ключі, вам слід замінити метод morphs на uuidMorphs або ulidMorphs у міграції таблиці сповіщень.

Форматування сповіщень бази даних

Якщо сповіщення підтримує зберігання в таблиці бази даних, ви повинні визначити метод toDatabase або toArray у класі сповіщення. Цей метод отримає сутність $notifiable і повинен повертати простий PHP масив. Повернений масив буде закодовано у формат JSON і збережено в стовпці data вашої таблиці notifications. Давайте розглянемо приклад методу toArray:

/**
 * Отримати представлення сповіщення у вигляді масиву.
 *
 * @return array<string, mixed>
 */
public function toArray(object $notifiable): array
{
    return [
        'invoice_id' => $this->invoice->id,
        'amount' => $this->invoice->amount,
    ];
}

Коли сповіщення зберігається в базі даних вашого застосунку, стовпець type за замовчуванням буде встановлено на ім'я класу сповіщення, а стовпець read_at буде null. Однак, ви можете налаштувати цю поведінку, визначивши методи databaseType та initialDatabaseReadAtValue у вашому класі сповіщення:

use Illuminate\Support\Carbon;
 
/**
 * Отримати тип бази даних сповіщення.
 */
public function databaseType(object $notifiable): string
{
    return 'invoice-paid';
}
 
/**
 * Отримати початкове значення для стовпця "read_at".
 */
public function initialDatabaseReadAtValue(): ?Carbon
{
    return null;
}

toDatabase проти toArray

Метод toArray також використовується каналом broadcast для визначення, які дані транслювати на ваш JavaScript-інтерфейс. Якщо ви хочете мати два різні представлення масиву для каналів database і broadcast, вам слід визначити метод toDatabase замість методу toArray.

Доступ до сповіщень

Після збереження сповіщень у базі даних, вам потрібен зручний спосіб доступу до них з ваших сповіщуваних сутностей. Трейт Illuminate\Notifications\Notifiable, який включено в модель Laravel за замовчуванням App\Models\User, містить notifications Eloquent-відношення, яке повертає сповіщення для сутності. Щоб отримати сповіщення, ви можете отримати доступ до цього методу, як і до будь-якого іншого Eloquent-відношення. За замовчуванням, сповіщення будуть відсортовані за міткою часу created_at з найновішими сповіщеннями на початку колекції:

$user = App\Models\User::find(1);
 
foreach ($user->notifications as $notification) {
    echo $notification->type;
}

Якщо ви хочете отримати лише "непрочитані" сповіщення, ви можете використовувати відношення unreadNotifications. Знову ж таки, ці сповіщення будуть відсортовані за міткою часу created_at з найновішими сповіщеннями на початку колекції:

$user = App\Models\User::find(1);
 
foreach ($user->unreadNotifications as $notification) {
    echo $notification->type;
}

Щоб отримати доступ до ваших сповіщень з вашого JavaScript-клієнта, ви повинні визначити контролер сповіщень для вашого застосунку, який повертає сповіщення для сповіщуваної сутності, такої як поточний користувач. Потім ви можете зробити HTTP-запит до URL цього контролера з вашого JavaScript-клієнта.

Позначення сповіщень як прочитані

Зазвичай, ви захочете позначити сповіщення як "прочитане", коли користувач переглядає його. Трейт Illuminate\Notifications\Notifiable надає метод markAsRead, який оновлює стовпець read_at у записі бази даних сповіщення:

$user = App\Models\User::find(1);
 
foreach ($user->unreadNotifications as $notification) {
    $notification->markAsRead();
}

Однак, замість того, щоб перебирати кожне сповіщення, ви можете використовувати метод markAsRead безпосередньо на колекції сповіщень:

$user->unreadNotifications->markAsRead();

Ви також можете використовувати запит на масове оновлення, щоб позначити всі сповіщення як прочитані, не отримуючи їх з бази даних:

$user = App\Models\User::find(1);
 
$user->unreadNotifications()->update(['read_at' => now()]);

Ви можете видалити сповіщення, щоб повністю видалити їх з таблиці:

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

Трансляція Сповіщень

Передумови

Перш ніж транслювати сповіщення, ви повинні налаштувати та ознайомитися з сервісами трансляції подій Laravel. Трансляція подій надає спосіб реагувати на події Laravel на стороні сервера з вашого фронтенду на JavaScript.

Форматування Сповіщень Трансляції

Канал broadcast транслює сповіщення, використовуючи сервіси трансляції подій Laravel, дозволяючи вашому JavaScript-інтерфейсу отримувати сповіщення в режимі реального часу. Якщо сповіщення підтримує трансляцію, ви можете визначити метод toBroadcast у класі сповіщення. Цей метод отримає сутність $notifiable і повинен повернути екземпляр BroadcastMessage. Якщо метод toBroadcast не існує, буде використано метод toArray для збору даних, які повинні бути транслювані. Повернені дані будуть закодовані у форматі JSON і транслюватимуться на ваш JavaScript-інтерфейс. Давайте розглянемо приклад методу toBroadcast:

use Illuminate\Notifications\Messages\BroadcastMessage;
 
/**
 * Отримати трансляційне представлення сповіщення.
 */
public function toBroadcast(object $notifiable): BroadcastMessage
{
    return new BroadcastMessage([
        'invoice_id' => $this->invoice->id,
        'amount' => $this->invoice->amount,
    ]);
}

Конфігурація черги трансляції

Усі сповіщення трансляції ставляться в чергу для трансляції. Якщо ви хочете налаштувати з'єднання черги або ім'я черги, яке використовується для постановки в чергу операції трансляції, ви можете використовувати методи onConnection та onQueue класу BroadcastMessage:

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

Налаштування типу сповіщення

На додаток до даних, які ви вказуєте, всі трансляційні сповіщення також мають поле type, що містить повне ім'я класу сповіщення. Якщо ви хочете налаштувати type сповіщення, ви можете визначити метод broadcastType у класі сповіщення:

/**
 * Отримати тип сповіщення, яке транслюється.
 */
public function broadcastType(): string
{
    return 'broadcast.message';
}

Прослуховування сповіщень

Сповіщення будуть транслюватися на приватному каналі, відформатованому за допомогою конвенції {notifiable}.{id}. Отже, якщо ви надсилаєте сповіщення до екземпляра App\Models\User з ID 1, сповіщення буде транслюватися на приватному каналі App.Models.User.1. Використовуючи Laravel Echo, ви можете легко слухати сповіщення на каналі за допомогою методу notification:

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

Використання React або Vue

Laravel Echo включає React та Vue хуки, які роблять прослуховування сповіщень безболісним. Щоб почати, викличте хук useEchoNotification, який використовується для прослуховування сповіщень. Хук useEchoNotification автоматично залишить канали, коли компонент, що використовує його, буде демонтовано:

import { useEchoNotification } from "@laravel/echo-react";
 
useEchoNotification(
    `App.Models.User.${userId}`,
    (notification) => {
        console.log(notification.type);
    },
);
<script setup lang="ts">
import { useEchoNotification } from "@laravel/echo-vue";
 
useEchoNotification(
    `App.Models.User.${userId}`,
    (notification) => {
        console.log(notification.type);
    },
);
</script>

За замовчуванням, хук слухає всі сповіщення. Щоб вказати типи сповіщень, які ви хочете слухати, ви можете надати або рядок, або масив типів до useEchoNotification:

import { useEchoNotification } from "@laravel/echo-react";
 
useEchoNotification(
    `App.Models.User.${userId}`,
    (notification) => {
        console.log(notification.type);
    },
    'App.Notifications.InvoicePaid',
);
<script setup lang="ts">
import { useEchoNotification } from "@laravel/echo-vue";
 
useEchoNotification(
    `App.Models.User.${userId}`,
    (notification) => {
        console.log(notification.type);
    },
    'App.Notifications.InvoicePaid',
);
</script>

Ви також можете вказати форму даних корисного навантаження сповіщення, забезпечуючи більшу безпеку типів і зручність редагування:

type InvoicePaidNotification = {
    invoice_id: number;
    created_at: string;
};
 
useEchoNotification<InvoicePaidNotification>(
    `App.Models.User.${userId}`,
    (notification) => {
        console.log(notification.invoice_id);
        console.log(notification.created_at);
        console.log(notification.type);
    },
    'App.Notifications.InvoicePaid',
);

Налаштування каналу сповіщень

Якщо ви хочете налаштувати, на якому каналі транслюються сповіщення про трансляцію сутності, ви можете визначити метод receivesBroadcastNotificationsOn на сутності, що може отримувати сповіщення:

<?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;
 
    /**
     * Канали, на яких користувач отримує трансляції сповіщень.
     */
    public function receivesBroadcastNotificationsOn(): string
    {
        return 'users.'.$this->id;
    }
}

SMS Сповіщення

Передумови

Надсилання SMS-повідомлень у Laravel здійснюється за допомогою Vonage (раніше відомого як Nexmo). Перш ніж ви зможете надсилати повідомлення через Vonage, вам потрібно встановити пакети laravel/vonage-notification-channel та guzzlehttp/guzzle:

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

Пакет включає файл конфігурації. Однак, вам не потрібно експортувати цей файл конфігурації до вашого власного застосунку. Ви можете просто використовувати змінні середовища VONAGE_KEY та VONAGE_SECRET для визначення ваших публічних та секретних ключів Vonage.

Після визначення ваших ключів, ви повинні встановити змінну середовища VONAGE_SMS_FROM, яка визначає номер телефону, з якого ваші SMS-повідомлення повинні відправлятися за замовчуванням. Ви можете згенерувати цей номер телефону в панелі керування Vonage:

VONAGE_SMS_FROM=15556666666

Форматування SMS-повідомлень

Якщо сповіщення підтримує відправку як SMS, ви повинні визначити метод toVonage у класі сповіщення. Цей метод отримає сутність $notifiable і повинен повернути екземпляр Illuminate\Notifications\Messages\VonageMessage:

use Illuminate\Notifications\Messages\VonageMessage;
 
/**
 * Отримати представлення сповіщення Vonage / SMS.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
        ->content('Ваша SMS');
}

Unicode вміст

Якщо ваше SMS-повідомлення міститиме символи Unicode, ви повинні викликати метод unicode при створенні екземпляра VonageMessage:

use Illuminate\Notifications\Messages\VonageMessage;
 
/**
 * Отримати представлення сповіщення Vonage / SMS.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
        ->content('Your unicode message')
        ->unicode();
}

Налаштування номера "Від"

Якщо ви хочете надіслати деякі сповіщення з номера телефону, який відрізняється від номера телефону, вказаного у вашій змінній середовища VONAGE_SMS_FROM, ви можете викликати метод from на екземплярі VonageMessage:

use Illuminate\Notifications\Messages\VonageMessage;
 
/**
 * Отримати представлення сповіщення Vonage / SMS.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
        ->content('Your SMS message content')
        ->from('15554443333');
}

Додавання посилання на клієнта

Якщо ви хочете відстежувати витрати на користувача, команду або клієнта, ви можете додати "клієнтське посилання" до сповіщення. Vonage дозволить вам створювати звіти, використовуючи це клієнтське посилання, щоб ви могли краще зрозуміти використання SMS певним клієнтом. Клієнтське посилання може бути будь-яким рядком до 40 символів:

use Illuminate\Notifications\Messages\VonageMessage;
 
/**
 * Отримати представлення сповіщення Vonage / SMS.
 */
public function toVonage(object $notifiable): VonageMessage
{
    return (new VonageMessage)
        ->clientReference((string) $notifiable->id)
        ->content('Your SMS message content');
}

Маршрутизація SMS сповіщень

Щоб направити сповіщення Vonage на правильний номер телефону, визначте метод routeNotificationForVonage у вашій сутності, що може отримувати сповіщення:

<?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;
 
    /**
     * Маршрутизація сповіщень для каналу Vonage.
     */
    public function routeNotificationForVonage(Notification $notification): string
    {
        return $this->phone_number;
    }
}

Сповіщення Slack

Передумови

Перш ніж надсилати сповіщення Slack, ви повинні встановити канал сповіщень Slack через компонувальник:

composer require laravel/slack-notification-channel

Крім того, ви повинні створити Slack App для вашого робочого простору Slack.

Якщо вам потрібно надсилати сповіщення лише в той самий Slack workspace, в якому створено додаток, ви повинні переконатися, що ваш додаток має області chat:write, chat:write.public та chat:write.customize. Ці області можна додати на вкладці управління додатком "OAuth & Permissions" у Slack.

Далі скопіюйте "Bot User OAuth Token" застосунку та розмістіть його в масиві конфігурації slack у файлі конфігурації services.php вашого застосунку. Цей токен можна знайти на вкладці "OAuth & Permissions" у Slack:

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

Розповсюдження додатків

Якщо ваш застосунок надсилатиме сповіщення до зовнішніх робочих просторів Slack, які належать користувачам вашого застосунку, вам потрібно буде "розповсюдити" ваш додаток через Slack. Розповсюдження додатку можна керувати з вкладки "Manage Distribution" вашого додатку в Slack. Після того як ваш додаток буде розповсюджено, ви можете використовувати Socialite для отримання токенів Slack Bot від імені користувачів вашого застосунку.

Форматування сповіщень Slack

Якщо сповіщення підтримує відправку як повідомлення в Slack, ви повинні визначити метод toSlack у класі сповіщення. Цей метод отримає сутність $notifiable і повинен повернути екземпляр Illuminate\Notifications\Slack\SlackMessage. Ви можете створювати насичені сповіщення, використовуючи Slack's Block Kit API. Наступний приклад може бути переглянутий у Slack's Block Kit builder:

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;
 
/**
 * Отримати представлення сповіщення у форматі Slack.
 */
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!');
        });
}

Використання шаблону Block Kit Builder від Slack

Замість використання методів побудови повідомлень для створення вашого повідомлення Block Kit, ви можете надати необроблений JSON-пакет, згенерований за допомогою Block Kit Builder від Slack, методу usingBlockKitTemplate:

use Illuminate\Notifications\Slack\SlackMessage;
use Illuminate\Support\Str;
 
/**
 * Отримати Slack-представлення сповіщення.
 */
public function toSlack(object $notifiable): SlackMessage
{
    $template = <<<JSON
        {
          "blocks": [
            {
              "type": "header",
              "text": {
                "type": "plain_text",
                "text": "Team Announcement"
              }
            },
            {
              "type": "section",
              "text": {
                "type": "plain_text",
                "text": "We are hiring!"
              }
            }
          ]
        }
    JSON;
 
    return (new SlackMessage)
        ->usingBlockKitTemplate($template);
}

Інтерактивність Slack

Система сповіщень Slack's Block Kit надає потужні можливості для обробки взаємодії з користувачем. Щоб використовувати ці можливості, ваш Slack App повинен мати увімкнену "Інтерактивність" і налаштовану "URL-адресу запиту", яка вказує на URL-адресу, що обслуговується вашим застосунком. Ці налаштування можна керувати з вкладки управління застосунком "Інтерактивність та ярлики" у Slack.

У наступному прикладі, який використовує метод actionsBlock, Slack надішле POST запит на ваш "URL запиту" з даними, що містять користувача Slack, який натиснув кнопку, ID натиснутої кнопки та інше. Ваш застосунок може визначити дію, яку слід виконати, на основі цих даних. Ви також повинні перевірити, що запит був зроблений 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;
 
/**
 * Отримати Slack-представлення сповіщення.
 */
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 за замовчуванням "button_acknowledge_invoice"...
            $block->button('Acknowledge Invoice')->primary();
 
            // Ручне налаштування ID...
            $block->button('Deny')->danger()->id('deny_invoice');
        });
}

Модальні вікна підтвердження

Якщо ви хочете, щоб користувачі повинні були підтвердити дію перед її виконанням, ви можете викликати метод confirm при визначенні вашої кнопки. Метод confirm приймає повідомлення та замикання, яке отримує екземпляр 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;
 
/**
 * Отримати Slack-представлення сповіщення.
 */
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');
                    }
                );
        });
}

Інспектування Slack блоків

Якщо ви хочете швидко перевірити блоки, які ви створювали, ви можете викликати метод dd на екземплярі SlackMessage. Метод dd згенерує та виведе URL до Block Kit Builder Slack, який відображає попередній перегляд вмісту та сповіщення у вашому браузері. Ви можете передати true до методу dd, щоб вивести необроблений вміст:

return (new SlackMessage)
    ->text('Один з ваших рахунків було оплачено!')
    ->headerBlock('Рахунок оплачено')
    ->dd();

Маршрутизація Slack сповіщень

Щоб направити сповіщення Slack до відповідної команди Slack та каналу, визначте метод routeNotificationForSlack у вашій моделі, що може отримувати сповіщення. Цей метод може повертати одне з трьох значень:

  • null - що передає маршрутизацію до каналу, налаштованого в самій нотифікації. Ви можете використовувати метод to при створенні вашого SlackMessage для налаштування каналу в межах нотифікації.
  • Рядок, що вказує Slack-канал для відправки сповіщення, напр. #support-channel.
  • Екземпляр SlackRoute, який дозволяє вказати OAuth токен та назву каналу, наприклад, SlackRoute::make($this->slack_channel, $this->slack_token). Цей метод слід використовувати для відправки сповіщень до зовнішніх робочих просторів.

Наприклад, повернення #support-channel з методу routeNotificationForSlack відправить сповіщення до каналу #support-channel у робочій області, пов'язаній з Bot User OAuth токеном, розташованим у файлі конфігурації services.php вашого застосунку:

<?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;
 
    /**
     * Маршрутизація сповіщень для каналу Slack.
     */
    public function routeNotificationForSlack(Notification $notification): mixed
    {
        return '#support-channel';
    }
}

Сповіщення зовнішніх робочих просторів Slack

Перш ніж надсилати сповіщення до зовнішніх робочих просторів Slack, ваш Slack App має бути розповсюджений.

Звичайно, ви часто захочете надсилати сповіщення до Slack робочих просторів, які належать користувачам вашого застосунку. Для цього вам спочатку потрібно отримати Slack OAuth токен для користувача. На щастя, Laravel Socialite включає драйвер Slack, який дозволить вам легко аутентифікувати користувачів вашого застосунку за допомогою Slack і отримати токен бота.

Як тільки ви отримаєте токен бота і збережете його в базі даних вашого застосунку, ви можете використовувати метод SlackRoute::make для маршрутизації сповіщення до робочого простору користувача. Крім того, ваш застосунок, ймовірно, повинен надати можливість користувачу вказати, до якого каналу слід надсилати сповіщення:

<?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;
 
    /**
     * Маршрутизація сповіщень для каналу Slack.
     */
    public function routeNotificationForSlack(Notification $notification): mixed
    {
        return SlackRoute::make($this->slack_channel, $this->slack_token);
    }
}

Локалізація Сповіщень

Laravel дозволяє надсилати сповіщення на локалі, відмінній від поточної локалі HTTP-запиту, і навіть запам'ятає цю локаль, якщо сповіщення поставлено в чергу.

Щоб досягти цього, клас Illuminate\Notifications\Notification пропонує метод locale для встановлення бажаної мови. Застосунок змінить цю локаль, коли сповіщення буде оцінюватися, а потім повернеться до попередньої локалі, коли оцінка буде завершена:

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

Локалізація декількох записів, що підлягають сповіщенню, також може бути досягнута за допомогою фасаду Notification:

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

Локалі, що надаються користувачем

Іноді застосунки зберігають бажану локаль кожного користувача. Реалізуючи контракт HasLocalePreference у вашій моделі, що може отримувати сповіщення, ви можете вказати Laravel використовувати цю збережену локаль при відправленні сповіщення:

use Illuminate\Contracts\Translation\HasLocalePreference;
 
class User extends Model implements HasLocalePreference
{
    /**
     * Отримати бажану локаль користувача.
     */
    public function preferredLocale(): string
    {
        return $this->locale;
    }
}

Як тільки ви реалізуєте інтерфейс, Laravel автоматично використовуватиме бажану локаль при відправленні сповіщень та листів до моделі. Тому немає потреби викликати метод locale при використанні цього інтерфейсу:

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

Тестування

Ви можете використовувати метод fake фасаду Notification, щоб запобігти відправленню сповіщень. Зазвичай, відправлення сповіщень не пов'язане з кодом, який ви фактично тестуєте. Найімовірніше, достатньо просто перевірити, що Laravel було вказано відправити певне сповіщення.

Після виклику методу fake фасаду Notification, ви можете перевірити, що сповіщення були надіслані користувачам, і навіть переглянути дані, які отримали сповіщення:

<?php
 
use App\Notifications\OrderShipped;
use Illuminate\Support\Facades\Notification;
 
test('orders can be shipped', function () {
    Notification::fake();
 
    // Виконати відправлення замовлення...
 
    // Перевірити, що жодного сповіщення не було надіслано...
    Notification::assertNothingSent();
 
    // Перевірити, що сповіщення було надіслано вказаним користувачам...
    Notification::assertSentTo(
        [$user], OrderShipped::class
    );
 
    // Перевірити, що сповіщення не було надіслано...
    Notification::assertNotSentTo(
        [$user], AnotherNotification::class
    );
 
    // Перевірити, що було надіслано вказану кількість сповіщень...
    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();
 
        // Виконати відправлення замовлення...
 
        // Перевірити, що жодного сповіщення не було надіслано...
        Notification::assertNothingSent();
 
        // Перевірити, що сповіщення було надіслано вказаним користувачам...
        Notification::assertSentTo(
            [$user], OrderShipped::class
        );
 
        // Перевірити, що сповіщення не було надіслано...
        Notification::assertNotSentTo(
            [$user], AnotherNotification::class
        );
 
        // Перевірити, що було надіслано вказану кількість сповіщень...
        Notification::assertCount(3);
    }
}

Ви можете передати замикання до методів assertSentTo або assertNotSentTo, щоб перевірити, що сповіщення було надіслано, яке проходить заданий "тест на істинність". Якщо було надіслано принаймні одне сповіщення, яке проходить заданий тест на істинність, тоді перевірка буде успішною:

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

Сповіщення на вимогу

Якщо код, який ви тестуєте, надсилає повідомлення на вимогу, ви можете перевірити, що повідомлення на вимогу було надіслано за допомогою методу assertSentOnDemand:

Notification::assertSentOnDemand(OrderShipped::class);

Передаючи замикання як другий аргумент методу assertSentOnDemand, ви можете визначити, чи було надіслано on-demand сповіщення на правильну адресу "маршруту":

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

Події Сповіщень

Подія Відправлення Сповіщення

Коли сповіщення відправляється, подія Illuminate\Notifications\Events\NotificationSending відправляється системою сповіщень. Це містить "notifiable" сутність та сам екземпляр сповіщення. Ви можете створити слухачі подій для цієї події у вашому застосунку:

use Illuminate\Notifications\Events\NotificationSending;
 
class CheckNotificationStatus
{
    /**
     * Обробити подію.
     */
    public function handle(NotificationSending $event): void
    {
        // ...
    }
}

Сповіщення не буде надіслано, якщо слухач події для події NotificationSending поверне false з методу handle:

/**
 * Обробити подію.
 */
public function handle(NotificationSending $event): bool
{
    return false;
}

У межах слухача подій ви можете отримати доступ до властивостей notifiable, notification і channel у події, щоб дізнатися більше про отримувача сповіщення або саме сповіщення:

/**
 * Обробити подію.
 */
public function handle(NotificationSending $event): void
{
    // $event->channel
    // $event->notifiable
    // $event->notification
}

Подія Надсилання Сповіщення

Коли сповіщення відправлено, Illuminate\Notifications\Events\NotificationSent подія відправляється системою сповіщень. Це містить "notifiable" сутність та сам екземпляр сповіщення. Ви можете створити слухачі подій для цієї події у вашому застосунку:

use Illuminate\Notifications\Events\NotificationSent;
 
class LogNotification
{
    /**
     * Обробити подію.
     */
    public function handle(NotificationSent $event): void
    {
        // ...
    }
}

У межах слухача подій ви можете отримати доступ до властивостей notifiable, notification, channel та response у події, щоб дізнатися більше про отримувача сповіщення або саме сповіщення:

/**
 * Обробити подію.
 */
public function handle(NotificationSent $event): void
{
    // $event->channel
    // $event->notifiable
    // $event->notification
    // $event->response
}

Користувацькі канали

Laravel постачається з кількома каналами сповіщень, але ви можете захотіти написати власні драйвери для доставки сповіщень через інші канали. Laravel робить це простим. Щоб почати, визначте клас, який містить метод send. Метод повинен отримувати два аргументи: $notifiable та $notification.

У межах методу send ви можете викликати методи на сповіщенні, щоб отримати об'єкт повідомлення, зрозумілий вашим каналом, а потім надіслати сповіщення до екземпляра $notifiable так, як вам зручно:

<?php
 
namespace App\Notifications;
 
use Illuminate\Notifications\Notification;
 
class VoiceChannel
{
    /**
     * Надіслати дане сповіщення.
     */
    public function send(object $notifiable, Notification $notification): void
    {
        $message = $notification->toVoice($notifiable);
 
        // Надіслати сповіщення до екземпляра $notifiable...
    }
}

Після того як ваш клас каналу сповіщень було визначено, ви можете повернути ім'я класу з методу via будь-якого з ваших сповіщень. У цьому прикладі метод toVoice вашого сповіщення може повертати будь-який об'єкт, який ви оберете для представлення голосових повідомлень. Наприклад, ви можете визначити свій власний клас VoiceMessage для представлення цих повідомлень:

<?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;
 
    /**
     * Отримати канали сповіщень.
     */
    public function via(object $notifiable): string
    {
        return VoiceChannel::class;
    }
 
    /**
     * Отримати голосове представлення сповіщення.
     */
    public function toVoice(object $notifiable): VoiceMessage
    {
        // ...
    }
}
Хостинг для Laravel – Ukraine