Дата обновления перевода 2021-06-02

Создание и отправка уведомлений¶

New in version 5.0: Компонент Notifier был представлен в Symfony 5.0.

Установка¶

Современные веб-приложения используют много каналов для отправки сообщений пользователям (такие как SMS, сообщения в Slack, email, push-уведомления и другие). Symfony-компонент Notifier - это абстракция над всеми этими каналами. Он предоставляет динамический способ управления как отправляются сообщения. Установите Notifier с помощью:

1	$ composer require symfony/notifier

Каналы: Chatters, Texters, Email и Browser¶

Компонент Notifier может отправлять уведомления разными каналами. Каждый канал может с помощью транспортов интегрироваться с разными провайдерами (например, Slack или Twilio SMS).

Комонент Notifier поддерживает такие каналы:

SMS канал отправляет уведомления на телефоны SMS-сообщениями;
Chat канал отправляет уведомления в чат-сервисы как Slack и Telegram;
Email канал интегрируется с Symfony Mailer;
Browser канал использует flash-сообщения.

Tip

Используйте секреты для безопасного хранения ваших API-токенов.

SMS канал¶

SMS канал использует классы Texter для отправки SMS-сообщений на мобильные телефоны. Эта функция требует подписки на внешние сервисы, которые отправляют SMS-сообщения. Symfony предоставляет интеграцию с несколькими популярными SMS-сервисами:

Сервис	Пакет	DSN
AllMySms	`symfony/allmysms-notifier`	`allmysms://LOGIN:APIKEY@default?from=FROM`
Clickatell	`symfony/clickatell-notifier`	`clickatell://ACCESS_TOKEN@default?from=FROM`
Esendex	`symfony/esendex-notifier`	`esendex://USER_NAME:PASSWORD@default?accountreference=ACCOUNT_REFERENCE&from=FROM`
FakeSms	`symfony/fake-sms-notifier`	`fakesms+email://MAILER_SERVICE_ID?to=TO&from=FROM`
FreeMobile	`symfony/free-mobile-notifier`	`freemobile://LOGIN:PASSWORD@default?phone=PHONE`
GatewayApi	`symfony/gatewayapi-notifier`	`gatewayapi://TOKEN@default?from=FROM`
Infobip	`symfony/infobip-notifier`	`infobip://TOKEN@default?from=FROM`
Iqsms	`symfony/iqsms-notifier`	`iqsms://LOGIN:PASSWORD@default?from=FROM`
LightSms	`symfony/light-sms-notifier`	`lightsms://LOGIN:TOKEN@default?from=PHONE`
MessageBird	`symfony/message-bird-notifier`	`messagebird://TOKEN@default?from=FROM`
Mobyt	`symfony/mobyt-notifier`	`mobyt://USER_KEY:ACCESS_TOKEN@default?from=FROM`
Nexmo	`symfony/nexmo-notifier`	`nexmo://KEY:SECRET@default?from=FROM`
Octopush	`symfony/octopush-notifier`	`octopush://USERLOGIN:APIKEY@default?from=FROM&type=TYPE`
OvhCloud	`symfony/ovhcloud-notifier`	`ovhcloud://APPLICATION_KEY:APPLICATION_SECRET@default?consumer_key=CONSUMER_KEY&service_name=SERVICE_NAME`
Sendinblue	`symfony/sendinblue-notifier`	`sendinblue://API_KEY@default?sender=PHONE`
Sinch	`symfony/sinch-notifier`	`sinch://ACCOUNT_ID:AUTH_TOKEN@default?from=FROM`
Smsapi	`symfony/smsapi-notifier`	`smsapi://TOKEN@default?from=FROM`
SmsBiuras	`symfony/sms-biuras-notifier`	`smsbiuras://UID:API_KEY@default?from=FROM&test_mode=0`
SpotHit	`symfony/spothit-notifier`	`spothit://TOKEN@default?from=FROM`
Twilio	`symfony/twilio-notifier`	`twilio://SID:TOKEN@default?from=FROM`

New in version 5.1: Интеграции OvhCloud, Sinch и FreeMobile появились в Symfony 5.1.

New in version 5.2: Интеграции Smsapi, Infobip, Mobyt, Esendex и Sendinblue появились в Symfony 5.2.

New in version 5.3: Интеграции Iqsms, GatewayApi, Octopush, AllMySms, Clickatell, SpotHit, FakeSms, LightSms, SmsBiuras и MessageBird были предсталены в Symfony 5.3.

Для включения texter, добавьте корректный DSN в ваш .env файл и настройте texter_transports:

# .env
TWILIO_DSN=twilio://SID:[email protected]?from=FROM

YAML

# config/packages/notifier.yaml
framework:
    notifier:
        texter_transports:
            twilio: '%env(TWILIO_DSN)%'

XML

<!-- config/packages/notifier.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:notifier>
            <framework:texter-transport name="twilio">
                %env(TWILIO_DSN)%
            </framework:texter-transport>
        </framework:notifier>
    </framework:config>
</container>

PHP

// config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    $framework->notifier()
        ->texterTransport('twilio', '%env(TWILIO_DSN)%')
    ;
};

Chat канал¶

Канал чатов используется для отправки сообщений пользователям в чаты используя классы Chatter. Symfony предоставляет интеграцию с этими сервисами чатов:

Сервис	Пакет	DSN
Discord	`symfony/discord-notifier`	`discord://TOKEN@default?webhook_id=ID`
FakeChat	`symfony/fake-chat-notifier`	`fakechat+email://default?to=TO&from=FROM`
Firebase	`symfony/firebase-notifier`	`firebase://USERNAME:PASSWORD@default`
Gitter	`symfony/gitter-notifier`	`gitter://TOKEN@default?room_id=ROOM_ID`
GoogleChat	`symfony/google-chat-notifier`	`googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?threadKey=THREAD_KEY`
LinkedIn	`symfony/linked-in-notifier`	`linkedin://TOKEN:USER_ID@default`
Mattermost	`symfony/mattermost-notifier`	`mattermost://TOKEN@ENDPOINT?channel=CHANNEL`
Mercure	`symfony/mercure-notifier`	`mercure://HUB_ID?topic=TOPIC`
MicrosoftTeams	`symfony/microsoft-teams-notifier`	`microsoftteams://default/PATH`
RocketChat	`symfony/rocket-chat-notifier`	`rocketchat://TOKEN@ENDPOINT?channel=CHANNEL`
Slack	`symfony/slack-notifier`	`slack://default/ID`
Telegram	`symfony/telegram-notifier`	`telegram://TOKEN@default?channel=CHAT_ID`
Zulip	`symfony/zulip-notifier`	`zulip://EMAIL:APIKEY@ENDPOINT?channel=CHANNEL`

New in version 5.1: Интеграции с Mattermost и RocketChat появились в Symfony 5.1. Slack DSN изменилась в Symfony 5.1 для использования Slack Incoming Webhooks вместо устаревших токенов.

New in version 5.2: Интеграции с GoogleChat, LinkedIn и Zulip появились в Symfony 5.2.

New in version 5.3: Интеграции Gitter, Mercure, FakeChat и Microsoft Teams были представлены в Symfony 5.3.

Chatters конфигурируются с помощью настройки chatter_transports:

# .env
SLACK_DSN=slack://[email protected]?channel=CHANNEL

YAML

# config/packages/notifier.yaml
framework:
    notifier:
        chatter_transports:
            slack: '%env(SLACK_DSN)%'

XML

<!-- config/packages/notifier.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:notifier>
            <framework:chatter-transport name="slack">
                %env(SLACK_DSN)%
            </framework:chatter-transport>
        </framework:notifier>
    </framework:config>
</container>

PHP

// config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    $framework->notifier()
        ->chatterTransport('slack', '%env(SLACK_DSN)%')
    ;
};

Email канал¶

Email канал использует Symfony Mailer для отправки уведомлений используя специальный NotificationEmail. Необходимо установить Twig bridge вместе с Inky и Twig расширениями CSS Inliner:

1	$ composer require symfony/twig-pack twig/cssinliner-extra twig/inky-extra

После этого настройте mailer. Вы также можете настроить адрес email с которого будут приходить письма-уведомления:

YAML

# config/packages/mailer.yaml
framework:
    mailer:
        dsn: '%env(MAILER_DSN)%'
        envelope:
            sender: '[email protected]'

XML

<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:mailer
            dsn="%env(MAILER_DSN)%"
        >
            <framework:envelope
                sender="[email protected]"
            />
        </framework:mailer>
    </framework:config>
</container>

PHP

// config/packages/mailer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    $framework->mailer()
        ->dsn('%env(MAILER_DSN)%')
        ->envelope()
            ->sender('[email protected]')
    ;
};

Настройка резервного транспорта или балансировка Round-Robin¶

Кроме настройки одного или нескольких отдельных транспортов вы также можете использовать специальные символы || и && для реализации резервного или round-robin транспорта:

YAML

# config/packages/notifier.yaml
framework:
    notifier:
        chatter_transports:
            # Отправлять уведомления в Slack и использовать Telegram, если
            # Slack выдал ошибку
            main: '%env(SLACK_DSN)% || %env(TELEGRAM_DSN)%'

            # Отправлять уведомления используя следующий запланированный транспорт, рассчитанный методом round robin
            roundrobin: '%env(SLACK_DSN)% && %env(TELEGRAM_DSN)%'

XML

<!-- config/packages/notifier.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:notifier>
            <!-- Отправлять уведомления в Slack и использовать Telegram, если
                 Slack выдал ошибку -->
            <framework:chatter-transport name="slack">
                %env(SLACK_DSN)% || %env(TELEGRAM_DSN)%
            </framework:chatter-transport>

            <!-- Отправлять уведомления используя следующий запланированный транспорт,
                 рассчитанный методом round robin -->
            <framework:chatter-transport name="slack"><![CDATA[
                %env(SLACK_DSN)% && %env(TELEGRAM_DSN)%
            ]]></framework:chatter-transport>
        </framework:notifier>
    </framework:config>
</container>

PHP

// config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    $framework->notifier()
        // Отправлять уведомления в Slack и использовать Telegram, если
        // Slack выдал ошибку
        ->chatterTransport('main', '%env(SLACK_DSN)% || %env(TELEGRAM_DSN)%')

        // Отправлять уведомления используя следующий запланированный транспорт, рассчитанный методом round robin
        ->chatterTransport('roundrobin', '%env(SLACK_DSN)% && %env(TELEGRAM_DSN)%')
    ;
};

Создание и отправка уведомлений¶

Для отправлки уведомления автоподключите NotifierInterface (ID сервиса - notifier). У этого класса есть метод send() который позволяет вам отправлять уведомление Notification получателю Recipient:

// src/Controller/InvoiceController.php
namespace App\Controller;

use Symfony\Component\Notifier\Notification\Notification;
use Symfony\Component\Notifier\NotifierInterface;
use Symfony\Component\Notifier\Recipient\Recipient;

class InvoiceController extends AbstractController
{
    /**
     * @Route("/invoice/create")
     */
    public function create(NotifierInterface $notifier)
    {
        // ...

        // Создать уведомление, которое отправится
        // через "email" канал
        $notification = (new Notification('New Invoice', ['email']))
            ->content('You got a new invoice for 15 EUR.');

        // Получатель уведомления
        $recipient = new Recipient(
            $user->getEmail(),
            $user->getPhonenumber()
        );

        // Отправить уведомление получателю
        $notifier->send($notification, $recipient);

        // ...
    }
}

Уведомление Notification создаётся с 2 аргументами: тема и каналы. Каналы указывают, какой канал или транспорт должен использоваться для отправки уведомления. Например, ['email', 'sms'] отправят и email и sms-уведомление пользователю.

Уведомление по умолчанию также имеет методы content() и emoji(), чтобы устанавливать содержание и иконку содержания.

Symfony предоставляет таких получателей:

NoRecipient: Получатель по умолчанию, который полезен, когда не нужно иметь информацию о получателе. Например, канал browser использует flashbag сессии текущего request;
Recipient: Может содержать и email и телефон пользователя. Этот получатель может использоваться для всех каналов (зависит от того установлены ли они действительно).

New in version 5.2: Класс AdminRecipient удалён в Symfony 5.2, используйте вместо него Recipient.

Конфигурация политики каналов¶

Вместо указания целевых каналов при создании Symfony также позволяет вам использовать уровни важности уведомлений. Обновите конфигурацию для указания какие каналы должны использоваться для нужных уровней (используя channel_policy):

YAML

# config/packages/notifier.yaml
framework:
    notifier:
        # ...
        channel_policy:
            # Использовать SMS, Slack и email для срочных уведомлений
            urgent: ['sms', 'chat/slack', 'email']

            # Использовать Slack для важных уведомлений
            high: ['chat/slack']

            # Использовать браузер для уведомлений среднего и низкого уровня
            medium: ['browser']
            low: ['browser']

XML

<!-- config/packages/notifier.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:notifier>
            <!-- ... -->

            <framework:channel-policy>
                <!-- Использовать SMS, Slack и email для срочных уведомлений -->
                <framework:urgent>sms</framework:urgent>
                <framework:urgent>chat/slack</framework:urgent>
                <framework:urgent>email</framework:urgent>

                <!-- Использовать Slack для важных уведомлений -->
                <framework:high>chat/slack</framework:high>

                <!-- Использовать браузер для уведомлений среднего и низкого уровня -->
                <framework:medium>browser</framework:medium>
                <framework:low>browser</framework:low>
            </framework:channel-policy>
        </framework:notifier>
    </framework:config>
</container>

PHP

// config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $framework->notifier()
        // Использовать SMS, Slack и email для срочных уведомлений
        ->channelPolicy('urgent', ['sms', 'chat/slack', 'email'])
        // Использовать Slack для важных уведомлений
        ->channelPolicy('high', ['chat/slack'])
        // Использовать браузер для уведомлений среднего и низкого уровня
        ->channelPolicy('medium', ['browser'])
        ->channelPolicy('medium', ['browser'])
    ;
};

Теперь, когда важность уведомления установлена в “high”, оно будет отправлено через транспорт Slack:

// ...
class InvoiceController extends AbstractController
{
    /**
     * @Route("/invoice/create")
     */
    public function invoice(NotifierInterface $notifier)
    {
        // ...

        $notification = (new Notification('New Invoice'))
            ->content('You got a new invoice for 15 EUR.')
            ->importance(Notification::IMPORTANCE_HIGH);

        $notifier->send($notification, new Recipient('[email protected]'));

        // ...
    }
}

Настройка уведомлений¶

Вы можете расширить базовые классы Notification или Recipient для настройки их поведения. Например, вы можете переопределить метод getChannels(), чтобы возвращать sms только есл сумма счёте очень большая и у получателя есть телефонный номер:

namespace App\Notifier;

use Symfony\Component\Notifier\Notification\Notification;
use Symfony\Component\Notifier\Recipient\RecipientInterface;
use Symfony\Component\Notifier\Recipient\SmsRecipientInterface;

class InvoiceNotification extends Notification
{
    private $price;

    public function __construct(int $price)
    {
        $this->price = $price;
    }

    public function getChannels(RecipientInterface $recipient)
    {
        if (
            $this->price > 10000
            && $recipient instanceof SmsRecipientInterface
        ) {
            return ['sms'];
        }

        return ['email'];
    }
}

Настройка сообщений уведомлений¶

У каждого канала есть собственный интерфейс уведомлений, который вы можете реализовать для настройки сообщений уведомлений. Например, если вы хотите изменить сообщение на основе сервиса chat, реализуйте ChatNotificationInterface и его метод asChatMessage():

// src/Notifier/InvoiceNotification.php
namespace App\Notifier;

use Symfony\Component\Notifier\Message\ChatMessage;
use Symfony\Component\Notifier\Notification\ChatNotificationInterface;
use Symfony\Component\Notifier\Notification\Notification;
use Symfony\Component\Notifier\Recipient\SmsRecipientInterface;

class InvoiceNotification extends Notification implements ChatNotificationInterface
{
    private $price;

    public function __construct(int $price)
    {
        $this->price = $price;
    }

    public function asChatMessage(RecipientInterface $recipient, string $transport = null): ?ChatMessage
    {
        // Добавьте свой emoji, если сообщение отправляется в Slack
        if ('slack' === $transport) {
            return (new ChatMessage('You\'re invoiced '.$this->price.' EUR.'))
                ->emoji('money');
        }

        // Если вы вернёте null, Notifier создаст ChatMessage
        // так как если бы этого метода не было
        return null;
    }
}

Также есть интерфейсы SmsNotificationInterface и EmailNotificationInterface для изменения сообщений, отправляемых по этим каналам.

Отключение доставки¶

Во время разработки и тестирования вы можете захотеть полностью отключить отправку уведомлений. Вы можете сделать это, дав Notifier транспорт NullTransport для всех настроенных транспортов texter и chatter, но только для dev (и/или test) окружений:

# config/packages/dev/notifier.yaml
framework:
    notifier:
        texter_transports:
            twilio: 'null://null'
        chatter_transports:
            slack: 'null://null'

Узнайте больше¶

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.

Содержание

Новые вакансии

PHP разработчик
🔥🚀 Горящая вакансия ⌨️💰

Создание и отправка уведомлений¶

Установка¶

Каналы: Chatters, Texters, Email и Browser¶

SMS канал¶

Chat канал¶

Email канал¶

Настройка резервного транспорта или балансировка Round-Robin¶

Создание и отправка уведомлений¶

Конфигурация политики каналов¶

Настройка уведомлений¶

Настройка сообщений уведомлений¶

Отключение доставки¶

Узнайте больше¶

Содержание

Новые вакансии

PHP разработчик 🔥🚀 Горящая вакансия ⌨️💰

Создание и отправка уведомлений¶

Установка¶

Каналы: Chatters, Texters, Email и Browser¶

SMS канал¶

Chat канал¶

Email канал¶

Настройка резервного транспорта или балансировка Round-Robin¶

Создание и отправка уведомлений¶

Конфигурация политики каналов¶

Настройка уведомлений¶

Настройка сообщений уведомлений¶

Отключение доставки¶

Узнайте больше¶

PHP разработчик
🔥🚀 Горящая вакансия ⌨️💰