Creating and Sending Notifications

Version: 5.4
Edit this page

Creating and Sending Notifications

5.0

The Notifier component was introduced in Symfony 5.0.

Installation

Current web applications use many different channels to send messages to the users (e.g. SMS, Slack messages, emails, push notifications, etc.). The Notifier component in Symfony is an abstraction on top of all these channels. It provides a dynamic way to manage how the messages are sent. Get the Notifier installed using:

1
$ composer require symfony/notifier

Channels: Chatters, Texters, Email, Browser and Push

The notifier component can send notifications to different channels. Each channel can integrate with different providers (e.g. Slack or Twilio SMS) by using transports.

The notifier component supports the following channels:

Tip

Use secrets to securely store your API's tokens.

SMS Channel

The SMS channel uses Texter classes to send SMS messages to mobile phones. This feature requires subscribing to a third-party service that sends SMS messages. Symfony provides integration with a couple popular SMS services:

Service Package DSN
AllMySms symfony/allmysms-notifier allmysms://LOGIN:[email protected]?from=FROM
AmazonSns symfony/amazon-sns-notifier sns://ACCESS_KEY:[email protected]?region=REGION
Clickatell symfony/clickatell-notifier clickatell://[email protected]?from=FROM
Esendex symfony/esendex-notifier esendex://USER_NAME:[email protected]?accountreference=ACCOUNT_REFERENCE&from=FROM
FakeSms symfony/fake-sms-notifier fakesms+email://MAILER_SERVICE_ID?to=TO&from=FROM or fakesms+logger://default
FreeMobile symfony/free-mobile-notifier freemobile://LOGIN:[email protected]?phone=PHONE
GatewayApi symfony/gatewayapi-notifier gatewayapi://[email protected]?from=FROM
Infobip symfony/infobip-notifier infobip://[email protected]?from=FROM
Iqsms symfony/iqsms-notifier iqsms://LOGIN:[email protected]?from=FROM
LightSms symfony/light-sms-notifier lightsms://LOGIN:[email protected]?from=PHONE
Mailjet symfony/mailjet-notifier mailjet://[email protected]?from=FROM
MessageBird symfony/message-bird-notifier messagebird://[email protected]?from=FROM
MessageMedia symfony/message-media-notifier messagemedia://API_KEY:[email protected]?from=FROM
Mobyt symfony/mobyt-notifier mobyt://USER_KEY:[email protected]?from=FROM
Nexmo symfony/nexmo-notifier nexmo://KEY:[email protected]?from=FROM
Octopush symfony/octopush-notifier octopush://USERLOGIN:[email protected]?from=FROM&type=TYPE
OvhCloud symfony/ovh-cloud-notifier ovhcloud://APPLICATION_KEY:[email protected]?consumer_key=CONSUMER_KEY&service_name=SERVICE_NAME
Sendinblue symfony/sendinblue-notifier sendinblue://[email protected]?sender=PHONE
Sms77 symfony/sms77-notifier sms77://[email protected]?from=FROM
Sinch symfony/sinch-notifier sinch://ACCOUNT_ID:[email protected]?from=FROM
Smsapi symfony/smsapi-notifier smsapi://[email protected]?from=FROM
SmsBiuras symfony/sms-biuras-notifier smsbiuras://UID:[email protected]?from=FROM&test_mode=0
Smsc symfony/smsc-notifier smsc://LOGIN:[email protected]?from=FROM
SpotHit symfony/spothit-notifier spothit://[email protected]?from=FROM
Telnyx symfony/telnyx-notifier telnyx://[email protected]?from=FROM&messaging_profile_id=MESSAGING_PROFILE_ID
TurboSms symfony/turbo-sms-notifier turbosms://[email protected]?from=FROM
Twilio symfony/twilio-notifier twilio://SID:[email protected]?from=FROM
Vonage symfony/vonage-notifier vonage://KEY:[email protected]?from=FROM
Yunpian symfony/yunpian-notifier yunpian://[email protected]

5.1

The OvhCloud, Sinch and FreeMobile integrations were introduced in Symfony 5.1.

5.2

The Smsapi, Infobip, Mobyt, Esendex and Sendinblue integrations were introduced in Symfony 5.2.

5.3

The Iqsms, GatewayApi, Octopush, AllMySms, Clickatell, SpotHit, FakeSms (email), LightSms, SmsBiuras and MessageBird integrations were introduced in Symfony 5.3.

5.4

The Nexmo integration was deprecated in Symfony 5.4, use the Vonage integration instead.

5.4

The MessageMedia, Smsc, Yunpian, AmazonSns, Telnyx, TurboSms, Mailjet, FakeSms (logger), Sms77 and Vonage integrations were introduced in Symfony 5.4.

To enable a texter, add the correct DSN in your .env file and configure the texter_transports:

1
2
# .env
TWILIO_DSN=twilio://SID:[email protected]?from=FROM
  • YAML
  • XML
  • PHP 
1
2
3
4
5
# config/packages/notifier.yaml
framework:
    notifier:
        texter_transports:
            twilio: '%env(TWILIO_DSN)%'

Chat Channel

The chat channel is used to send chat messages to users by using Chatter classes. Symfony provides integration with these chat services:

Service Package DSN
AmazonSns symfony/amazon-sns-notifier sns://ACCESS_KEY:[email protected]?region=REGION
Discord symfony/discord-notifier discord://[email protected]?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:[email protected]
Gitter symfony/gitter-notifier gitter://[email protected]?room_id=ROOM_ID
GoogleChat symfony/google-chat-notifier googlechat://ACCESS_KEY:[email protected]/SPACE?thread_key=THREAD_KEY
LinkedIn symfony/linked-in-notifier linkedin://TOKEN:[email protected]
Mattermost symfony/mattermost-notifier mattermost://[email protected]/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://[email protected]?channel=CHANNEL
Slack symfony/slack-notifier slack://[email protected]?channel=CHANNEL
Telegram symfony/telegram-notifier telegram://[email protected]?channel=CHAT_ID
Zulip symfony/zulip-notifier zulip://EMAIL:[email protected]?channel=CHANNEL

5.1

The Firebase, Mattermost and RocketChat integrations were introduced in Symfony 5.1. The Slack DSN changed in Symfony 5.1 to use Slack Incoming Webhooks instead of legacy tokens.

5.2

The GoogleChat, LinkedIn, Zulip and Discord integrations were introduced in Symfony 5.2. The Slack DSN changed in Symfony 5.2 to use Slack Web API again same as in 5.0.

5.3

The Gitter, Mercure, FakeChat (email) and Microsoft Teams integrations were introduced in Symfony 5.3.

5.4

The AmazonSns and FakeChat (logger) integrations were introduced in Symfony 5.4.

Chatters are configured using the chatter_transports setting:

1
2
# .env
SLACK_DSN=slack://[email protected]?channel=CHANNEL
  • YAML
  • XML
  • PHP 
1
2
3
4
5
# config/packages/notifier.yaml
framework:
    notifier:
        chatter_transports:
            slack: '%env(SLACK_DSN)%'

Email Channel

The email channel uses the Symfony Mailer to send notifications using the special NotificationEmail. It is required to install the Twig bridge along with the Inky and CSS Inliner Twig extensions:

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

After this, configure the mailer. You can also set the default "from" email address that should be used to send the notification emails:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
# config/packages/mailer.yaml
framework:
    mailer:
        dsn: '%env(MAILER_DSN)%'
        envelope:
            sender: '[email protected]'

Push Channel

The push channel is used to send notifications to users by using Texter classes. Symfony provides integration with these push services:

Service Package DSN
Firebase symfony/firebase-notifier firebase://USERNAME:[email protected]
Expo symfony/expo-notifier expo://[email protected]
OneSignal symfony/one-signal-notifier onesignal://APP_ID:[email protected]?defaultRecipientId=DEFAULT_RECIPIENT_ID''

5.4

The Expo and OneSignal integrations were introduced in Symfony 5.4.

To enable a texter, add the correct DSN in your .env file and configure the texter_transports:

1
2
# .env
EXPO_DSN=expo://[email protected]
  • YAML
  • XML
  • PHP 
1
2
3
4
5
# config/packages/notifier.yaml
framework:
    notifier:
        texter_transports:
            expo: '%env(EXPO_DSN)%'

Configure to use Failover or Round-Robin Transports

Besides configuring one or more separate transports, you can also use the special || and && characters to implement a failover or round-robin transport:

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
8
9
10
# config/packages/notifier.yaml
framework:
    notifier:
        chatter_transports:
            # Send notifications to Slack and use Telegram if
            # Slack errored
            main: '%env(SLACK_DSN)% || %env(TELEGRAM_DSN)%'

            # Send notifications to the next scheduled transport calculated by round robin
            roundrobin: '%env(SLACK_DSN)% && %env(TELEGRAM_DSN)%'

Creating & Sending Notifications

To send a notification, autowire the NotifierInterface (service ID notifier). This class has a send() method that allows you to send a Notification to a 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
32
33
// 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)
    {
        // ...

        // Create a Notification that has to be sent
        // using the "email" channel
        $notification = (new Notification('New Invoice', ['email']))
            ->content('You got a new invoice for 15 EUR.');

        // The receiver of the Notification
        $recipient = new Recipient(
            $user->getEmail(),
            $user->getPhonenumber()
        );

        // Send the notification to the recipient
        $notifier->send($notification, $recipient);

        // ...
    }
}

The Notification is created by using two arguments: the subject and channels. The channels specify which channel (or transport) should be used to send the notification. For instance, ['email', 'sms'] will send both an email and sms notification to the user.

The default notification also has a content() and emoji() method to set the notification content and icon.

Symfony provides the following recipients:

NoRecipient
This is the default and is useful when there is no need to have information about the receiver. For example, the browser channel uses the current requests' session flashbag;
Recipient
This can contain both the email address and the phone number of the user. This recipient can be used for all channels (depending on whether they are actually set).

5.2

The AdminRecipient class was removed in Symfony 5.2, you should use Recipient instead.

Configuring Channel Policies

Instead of specifying the target channels on creation, Symfony also allows you to use notification importance levels. Update the configuration to specify what channels should be used for specific levels (using channel_policy):

  • YAML
  • XML
  • PHP 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# config/packages/notifier.yaml
framework:
    notifier:
        # ...
        channel_policy:
            # Use SMS, Slack and email for urgent notifications
            urgent: ['sms', 'chat/slack', 'email']

            # Use Slack for highly important notifications
            high: ['chat/slack']

            # Use browser for medium and low notifications
            medium: ['browser']
            low: ['browser']

Now, whenever the notification's importance is set to "high", it will be sent using the Slack transport:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// ...
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]'));

        // ...
    }
}

Customize Notifications

You can extend the Notification or Recipient base classes to customize their behavior. For instance, you can overwrite the getChannels() method to only return sms if the invoice price is very high and the recipient has a phone number:

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
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'];
    }
}

Customize Notification Messages

Each channel has its own notification interface that you can implement to customize the notification message. For instance, if you want to modify the message based on the chat service, implement ChatNotificationInterface and its asChatMessage() method:

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
// 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
    {
        // Add a custom emoji if the message is sent to Slack
        if ('slack' === $transport) {
            return (new ChatMessage('You\'re invoiced '.$this->price.' EUR.'))
                ->emoji('money');
        }

        // If you return null, the Notifier will create the ChatMessage
        // based on this notification as it would without this method.
        return null;
    }
}

The SmsNotificationInterface and EmailNotificationInterface also exists to modify messages sent to those channels.

Disabling Delivery

While developing (or testing), you may want to disable delivery of notifications entirely. You can do this by forcing Notifier to use the NullTransport for all configured texter and chatter transports only in the dev (and/or test) environment:

1
2
3
4
5
6
7
# config/packages/dev/notifier.yaml
framework:
    notifier:
        texter_transports:
            twilio: 'null://null'
        chatter_transports:
            slack: 'null://null'
.. TODO
  • Using the message bus for asynchronous notification
  • Describe notifier monolog handler
  • Describe notification_on_failed_messages integration

Learn more

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.