Створення та відправлення сповіщень

Установка

Сучасні веб-додатки використовують багато каналів для відправлення повідомлень користувачам (такі як SMS, повідомлення в Slack, email, push-повідомлення та ін.). Компонент Symfony Notifier - це абстракція над усіма цими каналами. Він надає динамічний спосіб керування тим, як відправляються повідомлення. Встановіть Notifier за допомогою:

        1
        $ composer require symfony/notifier
    

Канали

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

Компонент Notifier підтримує такі канали:

SMS-канал відправляє сповіщення на телефони SMS-повідомленнями;
Чат-канал відправляє сповіщення у чат-сервіси, такі як Slack і Telegram;
Email-канал інтегрується з Symfony Mailer;
Браузер-канал використовує флеш-повідомлення .
Пуш-канал відправляє сповіщення на телефони та браузери за допомогою пуш-сповіщень.
Декстоп-канал відображає сповіщення на декстопі на тій же машині хостингу.

7.2

Канал Desktop був представлений в Symfony 7.2.

SMS-канал

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

Warning

Якщо будь-яке зі значень DSN містить будь-який символ, який вважається спеціальним в URI (на кшталт, : / ? # [ ] @ ! $ & ' ( ) * + , ; =), ви повинні зашифрувати їх. Див. RFC 3986, щоб побачити повний перелік зарезервованих символів, або використайте функцію urlencode, щоб зашифрувати їх.

??????	?????
46elks	?????????: `composer require symfony/forty-six-elks-notifier` DSN: `forty-six-elks://API_USERNAME:API_PASSWORD@default?from=FROM` ????????? ???-?????: ??
AllMySms	?????????: `composer require symfony/all-my-sms-notifier` DSN: `allmysms://LOGIN:APIKEY@default?from=FROM` ????????? ???-?????: ??
AmazonSns	?????????: `composer require symfony/amazon-sns-notifier` DSN: `sns://ACCESS_KEY:SECRET_KEY@default?region=REGION` ????????? ???-?????: ??
Bandwidth	?????????: `composer require symfony/bandwidth-notifier` DSN: `bandwidth://USERNAME:PASSWORD@default?from=FROM&account_id=ACCOUNT_ID&application_id=APPLICATION_ID&priority=PRIORITY` ????????? ???-?????: ??
Brevo	?????????: `composer require symfony/brevo-notifier` DSN: `brevo://API_KEY@default?sender=SENDER` ????????? ???-?????: ??
Clickatell	?????????: `composer require symfony/clickatell-notifier` DSN: `clickatell://ACCESS_TOKEN@default?from=FROM` ????????? ???-?????: ??
ContactEveryone	?????????: `composer require symfony/contact-everyone-notifier` DSN: `contact-everyone://TOKEN@default?&diffusionname=DIFFUSION_NAME&category=CATEGORY` ????????? ???-?????: No
Esendex	?????????: `composer require symfony/esendex-notifier` DSN: `esendex://USER_NAME:PASSWORD@default?accountreference=ACCOUNT_REFERENCE&from=FROM` ????????? ???-?????: ??
FakeSms	?????????: `composer require symfony/fake-sms-notifier` DSN: `fakesms+email://MAILER_SERVICE_ID?to=TO&from=FROM` or `fakesms+logger://default` ????????? ???-?????: ??
FreeMobile	?????????: `composer require symfony/free-mobile-notifier` DSN: `freemobile://LOGIN:API_KEY@default?phone=PHONE` ????????? ???-?????: ??
GatewayApi	?????????: `composer require symfony/gateway-api-notifier` DSN: `gatewayapi://TOKEN@default?from=FROM` ????????? ???-?????: ??
GoIP	?????????: `composer require symfony/go-ip-notifier` DSN: `goip://USERNAME:PASSWORD@HOST:80?sim_slot=SIM_SLOT` ????????? ???-?????: ??
Infobip	?????????: `composer require symfony/infobip-notifier` DSN: `infobip://AUTH_TOKEN@HOST?from=FROM` ????????? ???-?????: ??
Iqsms	?????????: `composer require symfony/iqsms-notifier` DSN: `iqsms://LOGIN:PASSWORD@default?from=FROM` ????????? ???-?????: ??
iSendPro	?????????: `composer require symfony/isendpro-notifier` DSN: `isendpro://ACCOUNT_KEY_ID@default?from=FROM&no_stop=NO_STOP&sandbox=SANDBOX` ????????? ???-?????: ??
KazInfoTeh	?????????: `composer require symfony/kaz-info-teh-notifier` DSN: `kaz-info-teh://USERNAME:PASSWORD@default?sender=FROM` ????????? ???-?????: ??
LightSms	?????????: `composer require symfony/light-sms-notifier` DSN: `lightsms://LOGIN:TOKEN@default?from=PHONE` ????????? ???-?????: ??
LOX24	?????????: `composer require symfony/lox24-notifier` DSN: `lox24://USER:TOKEN@default?from=FROM` ????????? ???-?????: ??
Mailjet	?????????: `composer require symfony/mailjet-notifier` DSN: `mailjet://TOKEN@default?from=FROM` ????????? ???-?????: ??
MessageBird	?????????: `composer require symfony/message-bird-notifier` DSN: `messagebird://TOKEN@default?from=FROM` ????????? ???-?????: ??
MessageMedia	?????????: `composer require symfony/message-media-notifier` DSN: `messagemedia://API_KEY:API_SECRET@default?from=FROM` ????????? ???-?????: ??
Mobyt	?????????: `composer require symfony/mobyt-notifier` DSN: `mobyt://USER_KEY:ACCESS_TOKEN@default?from=FROM` ????????? ???-?????: ??
Nexmo	?????????: `composer require symfony/nexmo-notifier` ????????? ?? ??????? Vonage (???. ?????)
Octopush	?????????: `composer require symfony/octopush-notifier` DSN: `octopush://USERLOGIN:APIKEY@default?from=FROM&type=TYPE` ????????? ???-?????: ??
OrangeSms	?????????: `composer require symfony/orange-sms-notifier` DSN: `orange-sms://CLIENT_ID:CLIENT_SECRET@default?from=FROM&sender_name=SENDER_NAME` ????????? ???-?????: ??
OvhCloud	?????????: `composer require symfony/ovh-cloud-notifier` DSN: `ovhcloud://APPLICATION_KEY:APPLICATION_SECRET@default?consumer_key=CONSUMER_KEY&service_name=SERVICE_NAME` ????????? ???-?????: ??
Plivo	?????????: `composer require symfony/plivo-notifier` DSN: `plivo://AUTH_ID:AUTH_TOKEN@default?from=FROM` ????????? ???-?????: ??
Primotexto	?????????: `composer require symfony/primotexto-notifier` DSN: `primotexto://API_KEY@default?from=FROM` ????????? ???-?????: ??
Redlink	?????????: `composer require symfony/redlink-notifier` DSN: `redlink://API_KEY:APP_KEY@default?from=SENDER_NAME&version=API_VERSION` ????????? ???-?????: ??
RingCentral	?????????: `composer require symfony/ring-central-notifier` DSN: `ringcentral://API_TOKEN@default?from=FROM` ????????? ???-?????: ??
Sendberry	?????????: `composer require symfony/sendberry-notifier` DSN: `sendberry://USERNAME:PASSWORD@default?auth_key=AUTH_KEY&from=FROM` ????????? ???-?????: ??
Sendinblue	?????????: `composer require symfony/sendinblue-notifier` DSN: `sendinblue://API_KEY@default?sender=PHONE` ????????? ???-?????: ??
Sms77	?????????: `composer require symfony/sms77-notifier` DSN: `sms77://API_KEY@default?from=FROM` ????????? ???-?????: ??
SimpleTextin	?????????: `composer require symfony/simple-textin-notifier` DSN: `simpletextin://API_KEY@default?from=FROM` ????????? ???-?????: ??
Sinch	?????????: `composer require symfony/sinch-notifier` DSN: `sinch://ACCOUNT_ID:AUTH_TOKEN@default?from=FROM` ????????? ???-?????: ??
Sipgate	?????????: `composer require symfony/sipgate-notifier` DSN: `sipgate://TOKEN_ID:TOKEN@default?senderId=SENDER_ID` ????????? ???-?????: ??
SmsSluzba	?????????: `composer require symfony/sms-sluzba-notifier` DSN: `sms-sluzba://USERNAME:PASSWORD@default` ????????? ???-?????: ??
Smsapi	?????????: `composer require symfony/smsapi-notifier` DSN: `smsapi://TOKEN@default?from=FROM` ????????? ???-?????: ??
Smsbox	?????????: `composer require symfony/smsbox-notifier` DSN: `smsbox://APIKEY@default?mode=MODE&strategy=STRATEGY&sender=SENDER` ????????? ???-?????: No
SmsBiuras	?????????: `composer require symfony/sms-biuras-notifier` DSN: `smsbiuras://UID:API_KEY@default?from=FROM&test_mode=0` ????????? ???-?????: ??
Smsc	?????????: `composer require symfony/smsc-notifier` DSN: `smsc://LOGIN:PASSWORD@default?from=FROM` ????????? ???-?????: ??
SMSense	?????????: `composer require smsense-notifier` DSN: `smsense://API_TOKEN@default?from=FROM` ????????? ???-?????: ??
SMSFactor	?????????: `composer require symfony/sms-factor-notifier` DSN: `sms-factor://TOKEN@default?sender=SENDER&push_type=PUSH_TYPE` ????????? ???-?????: ??
SpotHit	?????????: `composer require symfony/spot-hit-notifier` DSN: `spothit://TOKEN@default?from=FROM` ????????? ???-?????: ??
Sweego	?????????: `composer require symfony/sweego-notifier` DSN: `sweego://API_KEY@default?region=REGION&campaign_type=CAMPAIGN_TYPE` ????????? ???-?????: ???
Telnyx	?????????: `composer require symfony/telnyx-notifier` DSN: `telnyx://API_KEY@default?from=FROM&messaging_profile_id=MESSAGING_PROFILE_ID` ????????? ???-?????: ??
TurboSms	?????????: `composer require symfony/turbo-sms-notifier` DSN: `turbosms://AUTH_TOKEN@default?from=FROM` We????????? ???-?????: ??
Twilio	Install: `composer require symfony/twilio-notifier` DSN: `twilio://SID:TOKEN@default?from=FROM` ????????? ???-?????: ???
Unifonic	Install: `composer require symfony/unifonic-notifier` DSN: `unifonic://APP_SID@default?from=FROM` ????????? ???-?????: ??
Vonage	?????????: `composer require symfony/vonage-notifier` DSN: `vonage://KEY:SECRET@default?from=FROM` ????????? ???-?????: ???
Yunpian	?????????: `composer require symfony/yunpian-notifier` DSN: `yunpian://APIKEY@default` ????????? ???-?????: ??

Tip

Використовуйте секрети конфігурації Symfony для безпечного зберігання ваших API-токенів.

Tip

Деякі сторонні транспорти, при використанні API, підтримують зворотні виклики статусу через веб-хуки. Дивіться Документацію про веб-хуки для отримання додаткової інформації.

7.1

Інтеграції Smsbox, SmsSluzba, SMSense, LOX24 та Unifonic були представлені в Symfony 7.1.

7.2

Інтеграції Primotexto, Sipgate та Sweego були представлені в Symfony 7.2.

7.1

Інтеграція Sms77 застаріла, починаючи з Symfony 7.1, натомість використовуйте інтеграцію Seven.io.

Для ввімкнення texter, додайте коректний DSN у ваш файл .env та налаштуйте texter_transports:

        1
2
        # .env
TWILIO_DSN=twilio://SID:TOKEN@default?from=FROM
    

        1
2
3
4
5
        # config/packages/notifier.yaml
framework:
    notifier:
        texter_transports:
            twilio: '%env(TWILIO_DSN)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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>
    

        1
2
3
4
5
6
7
8
        // config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

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

Клас TexterInterface дозволяє вам відправляти SMS-повідомлення:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
        // src/Controller/SecurityController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\TexterInterface;
use Symfony\Component\Routing\Attribute\Route;

class SecurityController
{
    #[Route('/login/success')]
    public function loginSuccess(TexterInterface $texter): Response
    {
        $options = (new ProviderOptions())
            ->setPriority('high')
        ;

        $sms = new SmsMessage(
            // номер телефону, на який потрібно відправити SMS
            '+1411111111',
            // повідомлення
            'A new login was detected!',
            // опціонально, ви можете перевизначити "from", визначене за замовчуванням у транспорті
            '+1422222222',
        );

        $sentMessage = $texter->send($sms);

        // ...
    }
}
    

Метод send() повертає змінну типу SentMessage, яка надає інформацію на кшталт ID повідомлення та оригінального змісту повідомлення.

Чат-канал

Warning

Якщо будь-яке зі значень DSN містить будь-який символ, який вважається спеціальним в URI (на кшталт, : / ? # [ ] @ ! $ & ' ( ) * + , ; =), ви повинні зашифрувати їх. Див. RFC 3986, щоб побачити повний перелік зарезервованих символів, або використайте функцію urlencode, щоб зашифрувати їх.

Канал чатів використовується для відправлення повідомлень користувачам у чати, використовуючи класи Chatter. Symfony надає інтеграцію з цими сервісами чатів:

??????	?????	DSN
AmazonSns	`symfony/amazon-sns-notifier`	`sns://ACCESS_KEY:SECRET_KEY@default?region=REGION`
Bluesky	`symfony/bluesky-notifier`	`bluesky://USERNAME:PASSWORD@default`
Chatwork	`symfony/chatwork-notifier`	`chatwork://API_TOKEN@default?room_id=ID`
Discord	`symfony/discord-notifier`	`discord://TOKEN@default?webhook_id=ID`
FakeChat	`symfony/fake-chat-notifier`	`fakechat+email://default?to=TO&from=FROM` or `fakechat+logger://default`
Firebase	`symfony/firebase-notifier`	`firebase://USERNAME:PASSWORD@default`
GoogleChat	`symfony/google-chat-notifier`	`googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY`
LINE Bot	`symfony/line-bot-notifier`	`linebot://TOKEN@default?receiver=RECEIVER`
LINE Notify	`symfony/line-notify-notifier`	`linenotify://TOKEN@default`
LinkedIn	`symfony/linked-in-notifier`	`linkedin://TOKEN:USER_ID@default`
Mastodon	`symfony/mastodon-notifier`	`mastodon://ACCESS_TOKEN@HOST`
Mattermost	`symfony/mattermost-notifier`	`mattermost://ACCESS_TOKEN@HOST/PATH?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://TOKEN@default?channel=CHANNEL`
Telegram	`symfony/telegram-notifier`	`telegram://TOKEN@default?channel=CHAT_ID`
Twitter	`symfony/twitter-notifier`	`twitter://API_KEY:API_SECRET:ACCESS_TOKEN:ACCESS_SECRET@default`
Zendesk	`symfony/zendesk-notifier`	`zendesk://EMAIL:TOKEN@SUBDOMAIN`
Zulip	`symfony/zulip-notifier`	`zulip://EMAIL:TOKEN@HOST?channel=CHANNEL`

7.1

Інтеграція Bluesky була представлена в Symfony 7.1.

7.2

Інтеграція LINE Bot була представлена в Symfony 7.2.

7.2

Інтеграція Gitter була видалена в Symfony 7.2, тому що цей
сервіс більше не надає API.

Warning

За замовчуванням, якщо у вас встановлено компонент Messenger, сповіщення будуть надсилатися за допомогою MessageBus. Якщо у вас не запущено споживача повідомлень, повідомлення не будуть надіслані.

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

        1
2
3
4
        # config/packages/notifier.yaml
framework:
    notifier:
        message_bus: false
    

Чаттери конфігуруються за допомогою налаштування chatter_transports:

        1
2
        # .env
SLACK_DSN=slack://TOKEN@default?channel=CHANNEL
    

        1
2
3
4
5
        # config/packages/notifier.yaml
framework:
    notifier:
        chatter_transports:
            slack: '%env(SLACK_DSN)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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>
    

        1
2
3
4
5
6
7
8
        // config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

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

Клас ChatterInterface дозволяє вам відправляти повідомлення у чат-сервісах:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
        // src/Controller/CheckoutController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Notifier\ChatterInterface;
use Symfony\Component\Notifier\Message\ChatMessage;
use Symfony\Component\Routing\Attribute\Route;

class CheckoutController extends AbstractController
{
    #[Route('/checkout/thankyou')]
    public function thankyou(ChatterInterface $chatter): Response
    {
        $message = (new ChatMessage('You got a new invoice for 15 EUR.'))
            // якщо не встановлено чітко, повідомлення відправляється
            // транспорту за замовчуванням (першому сконфігурованому)
            ->transport('slack');

        $sentMessage = $chatter->send($message);

        // ...
    }
}
    

Метод send() повертає змінну типу SentMessage, яка надає інформацію на кшталт ID повідомлення та оригінального змісту повідомлення.

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 з якої будуть приходити листи-сповіщення:

        1
2
3
4
5
6
        # config/packages/mailer.yaml
framework:
    mailer:
        dsn: '%env(MAILER_DSN)%'
        envelope:
            sender: 'notifications@example.com'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        <!-- 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="notifications@example.com"
            />
        </framework:mailer>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
        // config/packages/mailer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->mailer()
        ->dsn(env('MAILER_DSN'))
        ->envelope()
            ->sender('notifications@example.com')
    ;
};
    

Push-канал

Caution

Якщо будь-яке зі значень DSN містить будь-який символ, який вважається спеціальним в URI (на кшталт, : / ? # [ ] @ ! $ & ' ( ) * + , ; =), ви повинні зашифрувати їх. Див. RFC 3986, щоб побачити повний перелік зарезервованих символів, або використайте функцію urlencode, щоб зашифрувати їх.

Push-канал використовується для відправлення користувачам сповіщень з використанням класів Texter. Symfony надає інтеграцію з цими пуш-сервісами:

??????	?????	DSN
Engagespot	`symfony/engagespot-notifier`	`engagespot://API_KEY@default?campaign_name=CAMPAIGN_NAME`
Expo	`symfony/expo-notifier`	`expo://Token@default`
Novu	`symfony/novu-notifier`	`novu://API_KEY@default`
Ntfy	`symfony/ntfy-notifier`	`ntfy://default/TOPIC`
OneSignal	`symfony/one-signal-notifier`	`onesignal://APP_ID:API_KEY@default?defaultRecipientId=DEFAULT_RECIPIENT_ID`
PagerDuty	`symfony/pager-duty-notifier`	`pagerduty://TOKEN@SUBDOMAIN`
Pushover	`symfony/pushover-notifier`	`pushover://USER_KEY:APP_TOKEN@default`
Pushy	`symfony/pushy-notifier`	`pushy://API_KEY@default`

Щоб увімкнути texter, додайте правильну DSN у ваш файл .env, та сконфігуруйте texter_transports:

7.1

Інтеграція Pushy була представлена в Symfony 7.1.

        1
2
        # .env
EXPO_DSN=expo://TOKEN@default
    

        1
2
3
4
5
        # config/packages/notifier.yaml
framework:
    notifier:
        texter_transports:
            expo: '%env(EXPO_DSN)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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="expo">
                %env(EXPO_DSN)%
            </framework:texter-transport>
        </framework:notifier>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
        // config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->notifier()
        ->texterTransport('expo', env('EXPO_DSN'))
    ;
};
    

Десктоп-канал

Декстоп-канал використовується для відображення локальних сповіщень на робочому столі на тій самій
хост-машині за допомогою класів Texter. Наразі, Symfony інтегровано з наступними постачальниками:

????????????	?????	DSN
JoliNotif	`symfony/joli-notif-notifier`	`jolinotif://default`

7.2

Міст JoliNotif був представлений в Symfony 7.2.

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

Додайте правильну DSN у ваш файл .env:

        1
2
        # .env
JOLINOTIF=jolinotif://default
    

Оновіть конфігурацію Notifier, щоб додати новий транспорт текстера:

        1
2
3
4
5
        # config/packages/notifier.yaml
framework:
    notifier:
        texter_transports:
            jolinotif: '%env(JOLINOTIF)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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="jolinotif">
                %env(JOLINOTIF)%
            </framework:texter-transport>
        </framework:notifier>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
        // config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->notifier()
        ->texterTransport('jolinotif', env('JOLINOTIF'))
    ;
};
    

Тепер ви можете надсилати сповіщення на ваш робочий стіл наступним чином:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
        // src/Notifier/SomeService.php
use Symfony\Component\Notifier\Message\DesktopMessage;
use Symfony\Component\Notifier\TexterInterface;
// ...

class SomeService
{
    public function __construct(
        private TexterInterface $texter,
    ) {
    }

    public function notifyNewSubscriber(User $user): void
    {
        $message = new DesktopMessage(
            'New subscription! 🎉',
            sprintf('%s is a new subscriber', $user->getFullName())
        );

        $texter->send($message);
    }
}
    

Ці сповіщення можна додатково налаштувати, і залежно від вашої операційної системи,
вони можуть підтримувати такі функції, як власні звуки, іконки тощо:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        use Symfony\Component\Notifier\Bridge\JoliNotif\JoliNotifOptions;
// ...

$options = (new JoliNotifOptions())
    ->setIconPath('/path/to/icons/error.png')
    ->setExtraOption('sound', 'sosumi')
    ->setExtraOption('url', 'https://example.com');

$message = new DesktopMessage('Production is down', <<<CONTENT
    ❌ Server prod-1 down
    ❌ Server prod-2 down
    ✅ Network is up
    CONTENT, $options);

$texter->send($message);
    

Конфігурація резервного транспорту або балансування Round-Robin

Окрім налаштування одного або декількох окремих транспортів, ви також можете викоритовувати спеціальні символи || і && для реалізації резервного або round-robin транспорту:

        1
2
3
4
5
6
7
8
9
10
        # 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)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
        <!-- 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>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $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:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
        // 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): Response
    {
        // ...

        // Створити сповіщення, яке відправиться
        // через "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: Отримувач за замовчуванням, який корисний, коли не треба мати інформацію про отримувача. Наприклад, браузер-канал використовує flashbag сесії поточного запиту;
Recipient: Може містити і email, і телефон користувача. Цей отримувач може використовуватися для всіх каналів (залежить від того, чи дійсно вони встановлені).

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

Замість вказування цільових каналів при створенні, Symfony також дозволяє вам використовувати рівні важливості сповіщень. Оновіть конфігурацію для вказання, які канали мають використовуватися для потрібних рівнів (використовуючи channel_policy):

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        # config/packages/notifier.yaml
framework:
    notifier:
        # ...
        channel_policy:
            # Використовувати SMS, Slack і email для термінових сповіщень
            urgent: ['sms', 'chat/slack', 'email']

            # Використовувати Slack для важливих сповіщень
            high: ['chat/slack']

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
        <!-- 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>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/packages/notifier.php
use Symfony\Config\FrameworkConfig;

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

Тепер, коли важливість сповіщення встановлена як "high", воно буде відправлене через транспорт Slack:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        // ...
class InvoiceController extends AbstractController
{
    #[Route('/invoice/create')]
    public function invoice(NotifierInterface $notifier): Response
    {
        // ...

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

        $notifier->send($notification, new Recipient('wouter@example.com'));

        // ...
    }
}
    

Користувацьке налаштування сповіщень

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
        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
{
    public function __construct(
        private int $price,
    ) {
    }

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

        return ['email'];
    }
}
    

Користувацьке налаштування повідомлень сповіщень

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
        // 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\RecipientInterface;

class InvoiceNotification extends Notification implements ChatNotificationInterface
{
    public function __construct(
        private int $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 та EmailNotificationInterface для зміни повідомлень, що надсилаються по цих каналах.

Користувацьке налаштування сповіщень браузера (флеш-повідомлення)

Поведінка сповіщень каналу браузера за замовчуванням - додавати флеш-повідомлення з notification в якості ключа.

Однак, ви можете захотіти вказати рівень важливості сповіщення типу флеш-повідомлення, щоб ви могли підлаштувати їх стиль.

Ви можете зробити це, перевизначивши сервіс за замовчуванням notifier.flash_message_importance_mapper на вашу власну реалізацію FlashMessageImportanceMapperInterface, де ви можете надати вашу власну "важливість" як "рівень небезпеки".

На даний момент Symfony надає реалізацію для типових рівнів небезпеки для CSS фреймворку Bootstrap, які ви можете реалізувати негайно, використавши:

        1
2
3
4
        # config/services.yaml
services:
    notifier.flash_message_importance_mapper:
        class: Symfony\Component\Notifier\FlashMessage\BootstrapFlashMessageImportanceMapper
    

        1
2
3
4
5
6
7
8
9
10
        <?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="notifier.flash_message_importance_mapper" class="Symfony\Component\Notifier\FlashMessage\BootstrapFlashMessageImportanceMapper"/>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\Notifier\FlashMessage\BootstrapFlashMessageImportanceMapper;

return function(ContainerConfigurator $containerConfigurator) {
    $containerConfigurator->services()
        ->set('notifier.flash_message_importance_mapper', BootstrapFlashMessageImportanceMapper::class)
    ;
};
    

Тестування Notifier

Symfony надає NotificationAssertionsTrait, які надають корисні методи для тестування вашої реалізації Notifier. Ви можете отримати переваги цього класу, використовуючи його напряму, або розширивши KernelTestCase.

Див. документацію тестування , щоб побачити список доступних тверджень.

Відключення доставки

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

        1
2
3
4
5
6
7
        # config/packages/dev/notifier.yaml
framework:
    notifier:
        texter_transports:
            twilio: 'null://null'
        chatter_transports:
            slack: 'null://null'
    

Використання подій

Клас Transport` компонента Notifier дозволяє вам опціонально підключатися до життєвого циклу через події.

Подія `MessageEvent::class`

Типові цілі: Зробити щось до відправки повідомлення (на кшталт логування того, яке повідомлення буде відправлено або відображення чогось про подію, яка буде виконана).

Прямо перед відправкою повідомлення, оголошується клас події MessageEvent. Слухачі отримують подію MessageEvent:

        1
2
3
4
5
6
7
8
9
        use Symfony\Component\Notifier\Event\MessageEvent;

$dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) {
    // отримує екземпляр повідомлення
    $message = $event->getMessage();

    // логувати щось
    $this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()'));
});
    

Подія `FailedMessageEvent`

Типові цілі: Зробити щось перед тим, як буде викликано виключення (повторно спробувати відправити повідомлення або записати лог додаткової інформації).

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

Слухачі отримують подію FailedMessageEvent:

        1
2
3
4
5
6
7
8
9
10
11
12
        use Symfony\Component\Notifier\Event\FailedMessageEvent;

$dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) {
    // отримує екземпляр повідомлення
    $message = $event->getMessage();

    // отримує екземпляр помилки
    $error = $event->getError();

    // логувати щось
    $this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()'));
});
    

Подія `SentMessageEvent`

Типові цілі: Виконати якусь дію, якщо повідомлення було відправлено успішно
(на кшталт отримання id, поверненого при відправці повідомлення).

Після того, як повідомлення було успішно відправено, оголошується клас події SentMessageEvent. Слухачі отримують подію SentMessageEvent:

        1
2
3
4
5
6
7
8
9
        use Symfony\Component\Notifier\Event\SentMessageEvent;

$dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) {
    // отримує екземпляр повідомлення
    $message = $event->getOriginalMessage();

    // логувати щось
    $this->logger(sprintf('The message has been successfully sent and has id: %s, $message->getMessageId()'));
});
    