From 4810fbfc6698c54b800003c4944ed4c460cd451f Mon Sep 17 00:00:00 2001 From: "gary.houbre" Date: Sat, 23 Nov 2019 16:53:10 +0100 Subject: [PATCH 1/6] WIP Notifer Page --- notifier.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 notifier.rst diff --git a/notifier.rst b/notifier.rst new file mode 100644 index 00000000000..40783e795fd --- /dev/null +++ b/notifier.rst @@ -0,0 +1,22 @@ +.. index:: + single: Notifier + +Notifier +======================== + +Sends notifications via one or more channels (email, SMS, Slack, Telegram, ...) + + +Installation +------------ + +First, run this command to install the notifier before using it: + +.. code-block:: terminal + + $ composer require symfony/notifier + + +Usage +------------ + From 34f23d0d6a0f13f42aad2e1892130e32e55c5fee Mon Sep 17 00:00:00 2001 From: andreybolonin Date: Wed, 25 Dec 2019 16:12:29 +0200 Subject: [PATCH 2/6] add notifier.rst --- components/notifier.rst | 158 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 152 insertions(+), 6 deletions(-) diff --git a/components/notifier.rst b/components/notifier.rst index 29fac4f81f0..5a7de10eb4d 100644 --- a/components/notifier.rst +++ b/components/notifier.rst @@ -1,5 +1,4 @@ .. index:: - single: Notifier single: Notifications single: Components; Notifier @@ -14,6 +13,9 @@ The Notifier Component The Notifier component was introduced in Symfony 5.0 as an :doc:`experimental feature `. +If you're using the Symfony Framework, read the +:doc:`Symfony Framework Notifier documentation `. + Installation ------------ @@ -23,11 +25,155 @@ Installation .. include:: /components/require_autoload.rst.inc - -Usage +Email ----- -.. caution:: +The Notifier component has notify you when something goes wrong:: + + use Symfony\Bridge\Twig\Mime\NotificationEmail; + use Symfony\Component\Mailer\Mailer; + use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport; + + $transport = new EsmtpTransport('localhost'); + $mailer = new Mailer($transport); + + $email = (new NotificationEmail()) + ->form('fabien@symfony.com') + ->to('fabien@symfony.com') + ->exception($exception); + + $mailer->send($email); + +The ``$email`` object is created via the :doc:`Mime component `. + +And configurable email template:: + + $email = (new NotificationEmail()) + ->htmlEmail('email/system.html.twig') + ->textEmail('email/system.txt.twig'); + +With template:: + + {% extends "@email/system.html.twig" %} + {% block style %} + {{ parent() }} + .container.body_alert { + border-top: 30px solid #ec5840; + } + {% endblock %} + {% block lines %} + This is an automated email for the MyApp application. + {{ parent() }} + {% endblock %} + {% block action %} + {{ parent() }} + + + {% endblock %} + {% block exception %}{% endblock %} + {% block footer_content %} +

© MyApp

+ {% endblock %} + + +SMS +--------- + +Sending SMS Messages the easy way:: + + /** + * @Route("/checkout/thankyou") + */ + public function thankyou(Texter $texter /* ... */) { + $sms = new SmsMessage('+1415999888', 'Revenue has just increased by 1€ per year!'); + $texter->send($sms); + + return $this->render('checkout/thankyou.html.twig', [ + // ... + ]); + } + +Below is the list of other popular provider with built-in support: + +================== +Service +================== +Telegram +Nexmo +Slack +Twilio +================== + +SMS low-level API:: + + $sms = new SmsMessage('+1415999888', 'Revenue has just increased!'); + $twilio = Transport::fromDsn('twilio://SID:TOKEN@default?from=FROM'); + $twilio->send($sms); + $nexmo = Transport::fromDsn('nexmo://KEY:SECRET@default?from=FROM'); + $nexmo->send($sms); + +SMS... higher-level API:: + + $texter = new Texter($twilio, $bus); + $texter->send($sms); + $transports = new Transports(['twilio' => $twilio, 'nexmo' => $nexmo]); + $texter = new Texter($transports, $bus); + $texter->send($sms); + $sms->setTransport('nexmo'); + $texter->send($sms); + $bus->dispatch($sms); + + $dsn = 'failover(twilio://SID:TOKEN@default?from=FROM nexmo://KEY:SECRET@default?from=FROM)'; + +Message +--------- + +Sending Messages the easy way:: + + /** + * @Route("/checkout/thankyou") + */ + public function thankyou(Chatter $chatter /* ... */) + { + $message = new ChatMessage('Revenue increased by 1€ per year...'); + $chatter->send($message); + return $this->render('checkout/thankyou.html.twig', [ + // ... + ]); + } + +Messages low-level API:: + + $message = new ChatMessage('Revenue increased by 1€ per year...'); + $slack = Transport::fromDsn('slack://TOKEN@default?channel=CHANNEL'); + $slack->send($sms); + $telegram = Transport::fromDsn('telegram://TOKEN@default?channel=CHAT_ID'); + $telegram->send($sms); + +Messages higher-level API:: + + $transports = Transport::fromDsns([ + 'slack' => 'slack://TOKEN@default?channel=CHANNEL', + 'telegram' => 'telegram://TOKEN@default?channel=CHAT_ID' + ]); + $chatter = new Chatter($transports, $bus); + $chatter->send($message); + $message->setTransport('telegram'); + $chatter->send($message); + $bus->dispatch($message); + + $options = (new SlackOptions()) + ->iconEmoji('tada') + ->iconUrl('https://symfony.com') + ->username('SymfonyNext') + ->channel($channel) + ->block((new SlackSectionBlock())->text('Some Text')) + ->block(new SlackDividerBlock()) + ->block((new SlackSectionBlock()) + ->text('Some Text in another block') + ->accessory(new SlackImageBlockElement('http://placekitten.com/700/500', 'kitten')) + ) + ; + $message = new ChatMessage('Default Text', $options); - We're still working on the docs of this component. Check this page again - in a few days. + $dsn = 'all(slack://TOKEN@default?channel=CHANNEL telegram://TOKEN@default?channel=CHAT_ID)'; From b9d0d7f261d506f7b848cd025919dc66b01b4edd Mon Sep 17 00:00:00 2001 From: Savvas Alexandrou Date: Mon, 20 Jan 2020 17:28:26 +0100 Subject: [PATCH 3/6] Slack notifier actions documentation --- components/notifier.rst | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/components/notifier.rst b/components/notifier.rst index 5a7de10eb4d..9990488aa47 100644 --- a/components/notifier.rst +++ b/components/notifier.rst @@ -177,3 +177,44 @@ Messages higher-level API:: $message = new ChatMessage('Default Text', $options); $dsn = 'all(slack://TOKEN@default?channel=CHANNEL telegram://TOKEN@default?channel=CHAT_ID)'; + +Slack Actions Block for Slack Message +------------------------------------- + +With a Slack Message you can add some interactive options called `Block elements`_:: + + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackActionsBlock; + use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + use Symfony\Component\Notifier\Chatter; + use Symfony\Component\Notifier\Bridge\Slack\SlackTransport; + + // Initialize a chatter with Slack Transport + $chatter = new Chatter(new SlackTransport('token')); + + // Create a message + $chatMessage = (new ChatMessage()) + ->subject('Contribute To Symfony'); + + // Create Slack Actions Block and add some buttons + $contributeToSymfonyBlocks = (new SlackActionsBlock()) + ->button( + 'Improve Documentation', + 'https://symfony.com/doc/current/contributing/documentation/standards.html', + 'primary' + ) + ->button( + 'Report bugs', + 'https://symfony.com/doc/current/contributing/code/bugs.html', + 'danger' + ); + $contributeToSymfonyOptions = (new SlackOptions())->block($contributeToSymfonyBlocks); + + // Add the Buttons as Options to the Message + $chatMessage->options($contributeToSymfonyOptions); + + // And then send the Message + $chatter->send($chatMessage); + + +.. _`Block elements`: https://api.slack.com/reference/block-kit/block-elements From 01793034f7f6f9551371d9642ea6e5b23c76b348 Mon Sep 17 00:00:00 2001 From: Savvas Alexandrou Date: Mon, 20 Jan 2020 17:50:23 +0100 Subject: [PATCH 4/6] Reorder the use statements alphabetically --- components/notifier.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/notifier.rst b/components/notifier.rst index 9990488aa47..267b4a80067 100644 --- a/components/notifier.rst +++ b/components/notifier.rst @@ -185,9 +185,9 @@ With a Slack Message you can add some interactive options called `Block elements use Symfony\Component\Notifier\Bridge\Slack\Block\SlackActionsBlock; use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; - use Symfony\Component\Notifier\Message\ChatMessage; - use Symfony\Component\Notifier\Chatter; use Symfony\Component\Notifier\Bridge\Slack\SlackTransport; + use Symfony\Component\Notifier\Chatter; + use Symfony\Component\Notifier\Message\ChatMessage; // Initialize a chatter with Slack Transport $chatter = new Chatter(new SlackTransport('token')); From 06f700944af2330573d0455dd7dd09d9e5a98c90 Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Sun, 2 Feb 2020 13:29:36 +0100 Subject: [PATCH 5/6] Add Notifier component documentation This merges the work of #12678, #12846, #12963 and finishes the main Notifier guide. --- _build/redirection_map | 1 + components/notifier.rst | 220 ---------------- index.rst | 1 + mailer.rst | 3 + notifier.rst | 564 +++++++++++++++++++++++++++++++++++++++- notifier/chatters.rst | 92 +++++++ notifier/texters.rst | 41 +++ 7 files changed, 693 insertions(+), 229 deletions(-) delete mode 100644 components/notifier.rst create mode 100644 notifier/chatters.rst create mode 100644 notifier/texters.rst diff --git a/_build/redirection_map b/_build/redirection_map index 5d44f67b39d..e446f199ff9 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -479,3 +479,4 @@ /components/translation/usage /translation /components/translation/custom_formats https://github.com/symfony/translation /components/translation/custom_message_formatter https://github.com/symfony/translation +/components/notifier https://github.com/symfony/notifier diff --git a/components/notifier.rst b/components/notifier.rst deleted file mode 100644 index 267b4a80067..00000000000 --- a/components/notifier.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. index:: - single: Notifications - single: Components; Notifier - -The Notifier Component -====================== - - The Notifier component sends notifications via one or more channels - (email, SMS, Slack, ...). - -.. versionadded:: 5.0 - - The Notifier component was introduced in Symfony 5.0 as an - :doc:`experimental feature `. - -If you're using the Symfony Framework, read the -:doc:`Symfony Framework Notifier documentation `. - -Installation ------------- - -.. code-block:: terminal - - $ composer require symfony/notifier - -.. include:: /components/require_autoload.rst.inc - -Email ------ - -The Notifier component has notify you when something goes wrong:: - - use Symfony\Bridge\Twig\Mime\NotificationEmail; - use Symfony\Component\Mailer\Mailer; - use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport; - - $transport = new EsmtpTransport('localhost'); - $mailer = new Mailer($transport); - - $email = (new NotificationEmail()) - ->form('fabien@symfony.com') - ->to('fabien@symfony.com') - ->exception($exception); - - $mailer->send($email); - -The ``$email`` object is created via the :doc:`Mime component `. - -And configurable email template:: - - $email = (new NotificationEmail()) - ->htmlEmail('email/system.html.twig') - ->textEmail('email/system.txt.twig'); - -With template:: - - {% extends "@email/system.html.twig" %} - {% block style %} - {{ parent() }} - .container.body_alert { - border-top: 30px solid #ec5840; - } - {% endblock %} - {% block lines %} - This is an automated email for the MyApp application. - {{ parent() }} - {% endblock %} - {% block action %} - {{ parent() }} - - - {% endblock %} - {% block exception %}{% endblock %} - {% block footer_content %} -

© MyApp

- {% endblock %} - - -SMS ---------- - -Sending SMS Messages the easy way:: - - /** - * @Route("/checkout/thankyou") - */ - public function thankyou(Texter $texter /* ... */) { - $sms = new SmsMessage('+1415999888', 'Revenue has just increased by 1€ per year!'); - $texter->send($sms); - - return $this->render('checkout/thankyou.html.twig', [ - // ... - ]); - } - -Below is the list of other popular provider with built-in support: - -================== -Service -================== -Telegram -Nexmo -Slack -Twilio -================== - -SMS low-level API:: - - $sms = new SmsMessage('+1415999888', 'Revenue has just increased!'); - $twilio = Transport::fromDsn('twilio://SID:TOKEN@default?from=FROM'); - $twilio->send($sms); - $nexmo = Transport::fromDsn('nexmo://KEY:SECRET@default?from=FROM'); - $nexmo->send($sms); - -SMS... higher-level API:: - - $texter = new Texter($twilio, $bus); - $texter->send($sms); - $transports = new Transports(['twilio' => $twilio, 'nexmo' => $nexmo]); - $texter = new Texter($transports, $bus); - $texter->send($sms); - $sms->setTransport('nexmo'); - $texter->send($sms); - $bus->dispatch($sms); - - $dsn = 'failover(twilio://SID:TOKEN@default?from=FROM nexmo://KEY:SECRET@default?from=FROM)'; - -Message ---------- - -Sending Messages the easy way:: - - /** - * @Route("/checkout/thankyou") - */ - public function thankyou(Chatter $chatter /* ... */) - { - $message = new ChatMessage('Revenue increased by 1€ per year...'); - $chatter->send($message); - return $this->render('checkout/thankyou.html.twig', [ - // ... - ]); - } - -Messages low-level API:: - - $message = new ChatMessage('Revenue increased by 1€ per year...'); - $slack = Transport::fromDsn('slack://TOKEN@default?channel=CHANNEL'); - $slack->send($sms); - $telegram = Transport::fromDsn('telegram://TOKEN@default?channel=CHAT_ID'); - $telegram->send($sms); - -Messages higher-level API:: - - $transports = Transport::fromDsns([ - 'slack' => 'slack://TOKEN@default?channel=CHANNEL', - 'telegram' => 'telegram://TOKEN@default?channel=CHAT_ID' - ]); - $chatter = new Chatter($transports, $bus); - $chatter->send($message); - $message->setTransport('telegram'); - $chatter->send($message); - $bus->dispatch($message); - - $options = (new SlackOptions()) - ->iconEmoji('tada') - ->iconUrl('https://symfony.com') - ->username('SymfonyNext') - ->channel($channel) - ->block((new SlackSectionBlock())->text('Some Text')) - ->block(new SlackDividerBlock()) - ->block((new SlackSectionBlock()) - ->text('Some Text in another block') - ->accessory(new SlackImageBlockElement('http://placekitten.com/700/500', 'kitten')) - ) - ; - $message = new ChatMessage('Default Text', $options); - - $dsn = 'all(slack://TOKEN@default?channel=CHANNEL telegram://TOKEN@default?channel=CHAT_ID)'; - -Slack Actions Block for Slack Message -------------------------------------- - -With a Slack Message you can add some interactive options called `Block elements`_:: - - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackActionsBlock; - use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; - use Symfony\Component\Notifier\Bridge\Slack\SlackTransport; - use Symfony\Component\Notifier\Chatter; - use Symfony\Component\Notifier\Message\ChatMessage; - - // Initialize a chatter with Slack Transport - $chatter = new Chatter(new SlackTransport('token')); - - // Create a message - $chatMessage = (new ChatMessage()) - ->subject('Contribute To Symfony'); - - // Create Slack Actions Block and add some buttons - $contributeToSymfonyBlocks = (new SlackActionsBlock()) - ->button( - 'Improve Documentation', - 'https://symfony.com/doc/current/contributing/documentation/standards.html', - 'primary' - ) - ->button( - 'Report bugs', - 'https://symfony.com/doc/current/contributing/code/bugs.html', - 'danger' - ); - $contributeToSymfonyOptions = (new SlackOptions())->block($contributeToSymfonyBlocks); - - // Add the Buttons as Options to the Message - $chatMessage->options($contributeToSymfonyOptions); - - // And then send the Message - $chatter->send($chatMessage); - - -.. _`Block elements`: https://api.slack.com/reference/block-kit/block-elements diff --git a/index.rst b/index.rst index ac293625cb9..423b4407cc5 100644 --- a/index.rst +++ b/index.rst @@ -47,6 +47,7 @@ Topics mercure messenger migration + notifier performance profiler routing diff --git a/mailer.rst b/mailer.rst index d407a0568c6..8b57e872ec8 100644 --- a/mailer.rst +++ b/mailer.rst @@ -12,6 +12,9 @@ integration, CSS inlining, file attachments and a lot more. Get them installed w $ composer require symfony/mailer + +.. _mailer-transport-setup: + Transport Setup --------------- diff --git a/notifier.rst b/notifier.rst index 40783e795fd..741529fbf2f 100644 --- a/notifier.rst +++ b/notifier.rst @@ -1,22 +1,568 @@ .. index:: single: Notifier -Notifier -======================== +Creating and Sending Notifications +================================== -Sends notifications via one or more channels (email, SMS, Slack, Telegram, ...) +.. versionadded:: 5.0 + The Notifier component was introduced in Symfony 5.0 as an + :doc:`experimental feature `. -Installation ------------- - -First, run this command to install the notifier before using it: +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 send. +Get the Notifier installed using: .. code-block:: terminal $ composer require symfony/notifier +Channels: Chatters, Texters, Email and Browser +---------------------------------------------- + +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: + +* `SMS `_ sends notifications to phones via SMS messages +* `Chat `_ sends notifications to chat services like Slack + and Telegram; +* `Email `_ integrating the :doc:`Symfony Mailer `; +* Browser using :ref:`flash messages `. + +.. tip:: + + Use :doc:`secrets ` to securily store your + API's tokens. + +.. _notifier-texter-dsn: + +SMS Channel +~~~~~~~~~~~ + +The SMS channel uses :class:`Symfony\\Component\\Notifier\\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 +======= =========================== ======================================== +Twilio ``symfony/twilio-notifier`` ``twilio://SID:TOKEN@default?from=FROM`` +Nexmo ``symfony/nexmo-notifier`` ``nexmo://KEY:SECRET@default?from=FROM`` +======= =========================== ======================================== + +To enable a texter, add the add the correct DSN in your ``.env`` file and +configure the ``texter_transports``: + +.. code-block:: bash + + # .env + TWILIO_DSN=twilio://SID:TOKEN@default?from=FROM + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/notifier.yaml + framework: + notifier: + texter_transports: + twilio: '%env(TWILIO_DSN)%' + + .. code-block:: xml + + + + + + + + + %env(TWILIO_DSN)% + + + + + + .. code-block:: php + + # config/packages/notifier.php + $container->loadFromExtension('framework', [ + 'notifier' => [ + 'texter_transports' => [ + 'twilio' => '%env(TWILIO_DSN)%', + ], + ], + ]); + +.. _notifier-chatter-dsn: + +Chat Channel +~~~~~~~~~~~~ + +The chat channel is used to send chat messages to users by using +:class:`Symfony\\Component\\Notifier\\Chatter` classes. Symfony provides +integration with these chat services: + +======== ============================= ============================================ +Service Package DSN +======== ============================= ============================================ +Slack ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL`` +Telegram ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID`` +======== ============================= ============================================ + +Chatters are configured using the ``chatter_transports`` setting: + +.. code-block:: bash + + # .env + SLACK_DSN=slack://TOKEN@default?channel=CHANNEL + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/notifier.yaml + framework: + notifier: + chatter_transports: + slack: '%env(SLACK_DSN)%' + + .. code-block:: xml + + + + + + + + + %env(SLACK_DSN)% + + + + + + .. code-block:: php + + # config/packages/notifier.php + $container->loadFromExtension('framework', [ + 'notifier' => [ + 'chatter_transports' => [ + 'slack' => '%env(SLACK_DSN)%', + ], + ], + ]); + +Email Channel +~~~~~~~~~~~~~ + +The email channel uses the :doc:`Symfony Mailer ` to send +notifications using the special +:class:`Symfony\\Bridge\\TwigBridge\\Mime\\NotificationEmail`. It is +required to install the Twig bridge along with the Inky and CSS Inliner +Twig extensions: + +.. code-block:: terminal + + $ composer require symfony/twig-pack twig/cssinliner-extra twig/inky-extra + +After this, :ref:`configure the mailer `. You can +also set the default "from" email address that should be used to send the +notification emails: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/mailer.yaml + framework: + mailer: + dsn: '%env(MAILER_DSN)%' + envelope: + sender: 'notifications@example.com' + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + # config/packages/mailer.php + $container->loadFromExtension('framework', [ + 'mailer' => [ + 'dsn' => '%env(MAILER_DSN)%', + 'envelope' => [ + 'sender' => 'notifications@example.com', + ], + ], + ]); + +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: + +.. configuration-block:: + + .. code-block:: yaml + + # 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)%' + + # Always send notifications to both Slack and Telegram + all: '%env(SLACK_DSN)% && %env(TELEGRAM_DSN)%' + + .. code-block:: xml + + + + + + + + + + %env(SLACK_DSN)% || %env(TELEGRAM_DSN)% + + + + + %env(SLACK_DSN)% && %env(TELEGRAM_DSN)% + + + + + + .. code-block:: php + + # config/packages/notifier.php + $container->loadFromExtension('framework', [ + 'notifier' => [ + 'chatter_transports' => [ + // Send notifications to Slack and use Telegram if + // Slack errored + 'main' => '%env(SLACK_DSN)% || %env(TELEGRAM_DSN)%', + + // Always send notifications to both Slack and Telegram + 'all' => '%env(SLACK_DSN)% && %env(TELEGRAM_DSN)%', + ], + ], + ]); + +Creating & Sending Notifications +-------------------------------- + +To send a notification, autowire the +:class:`Symfony\\Component\\Notifier\\NotifierInterface` (service ID +``notifier``). This class has a ``send()`` method that allows you to send a +:class:`Symfony\\Component\\Notifier\\Notification\\Notification` to a +:class:`Symfony\\Component\\Notifier\\Recipient\\Recipient`:: + + // src/Controller/InvoiceController.php + namespace App\Controller; + + use Symfony\Component\Notifier\Notification\Notification; + use Symfony\Component\Notifier\NotifierInterface; + use Symfony\Component\Notifier\Recipient\AdminRecipient; + + 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 AdminRecipient( + $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. It is required to specify +the transport when using chatters (e.g. ``['email', 'chat/telegram']``). + +The default notification also has a ``content()`` and ``emoji()`` method to +set the notification content and icon. + +Symfony provides three types of recipients: + +:class:`Symfony\\Component\\Notifier\\Recipient\\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's :ref:`session flashbag `; + +:class:`Symfony\\Component\\Notifier\\Recipient\\Recipient`` + This contains only the email address of the user and can be used for + messages on the email and browser channel; + +:class:`Symfony\\Component\\Notifier\\Recipient\\AdminRecipient``. + This can contain both email address and phonenumber of the user. This + recipient can be used for all channels (depending on whether they are + actually set). + +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``): + +.. configuration-block:: + + .. code-block:: yaml + + # 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'] + + .. code-block:: xml + + + + + + + + + + + + sms + chat/slack + email + + + chat/slack + + + browser + browser + + + + + + .. code-block:: php + + # config/packages/notifier.php + $container->loadFromExtension('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:: + + // ... + 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('wouter@wouterj.nl')); + + // ... + } + } + +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 phonenumber:: + + namespace App\Notifier; + + use Symfony\Component\Notifier\Notification\Notification; + use Symfony\Component\Notifier\Recipient\Recipient; + + class InvoiceNotification extends Notification + { + private $price; + + public function __construct(int $price) + { + $this->price = $price; + } + + public function getChannels(Recipient $recipient) + { + if ( + $this->price > 10000 + && $recipient instanceof AdminRecipient + && null !== $recipient->getPhone() + ) { + return ['sms', 'email']; + } + + 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 +:class:`Symfony\\Component\\Notifier\\Notification\\ChatNotificationInterface` +and its ``asChatMessage()`` method:: + + // 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\Recipient; + + class InvoiceNotification extends Notification implements ChatNotificationInterface + { + private $price; + + public function __construct(int $price) + { + $this->price = $price; + } + + public function asChatMessage(Recipient $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 +:class:`Symfony\\Component\\Notifier\\Notification\\SmsNotificationInterface` +and +:class:`Symfony\\Component\\Notifier\\Notification\\EmailNotificationInterface` +also exists to modify messages send to those channels. + +.. TODO + - Using the message bus for asynchronous notification + - Describe notifier monolog handler + - Describe notification_on_failed_messages integration + +Learn more +---------- -Usage ------------- +.. toctree:: + :maxdepth: 1 + :glob: + notifier/* diff --git a/notifier/chatters.rst b/notifier/chatters.rst new file mode 100644 index 00000000000..4850c96e0e8 --- /dev/null +++ b/notifier/chatters.rst @@ -0,0 +1,92 @@ +.. index:: + single: Notifier; Chatters + +How to send Chat Messages +========================= + +.. versionadded:: 5.0 + + The Notifier component was introduced in Symfony 5.0 as an + :doc:`experimental feature `. + +The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows +you to sent messages to chat services like Slack or Telegram:: + + // src/Controller/CheckoutController.php + namespace App\Controller; + + use Symfony\Component\Notifier\Notification\Notification; + use Symfony\Component\Notifier\NotifierInterface; + use Symfony\Component\Notifier\Recipient\AdminRecipient; + + class CheckoutController extends AbstractController + { + /** + * @Route("/checkout/thankyou") + */ + public function thankyou(ChatterInterface $chatter) + { + $message = (new ChatMessage('You got a new invoice for 15 EUR.')) + // if not set explicitly, the message is send to the + // default transport (the first one configured) + ->transport('slack'); + + $chatter->send($message); + + // ... + } + } + +.. seealso:: + + Read :ref:`the main Notifier guide ` to see how + to configure the different transports. + +Adding Interactions to a Slack Message +-------------------------------------- + +With a Slack message, you can use the +:class:`Symfony\\Component\\Notifier\\Bridge\\Slack\\SlackOptions` to add +some interactive options called `Block elements`_:: + + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackActionsBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackImageBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; + use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage('Contribute To Symfony'); + + // Create Slack Actions Block and add some buttons + $contributeToSymfonyBlocks = (new SlackActionsBlock()) + ->button( + 'Improve Documentation', + 'https://symfony.com/doc/current/contributing/documentation/standards.html', + 'primary' + ) + ->button( + 'Report bugs', + 'https://symfony.com/doc/current/contributing/code/bugs.html', + 'danger' + ); + + $slackOptions = (new SlackOptions()) + ->block((new SlackSectionBlock()) + ->text('The Symfony Community') + ->accessory( + new SlackImageBlockElement( + 'https://example.com/symfony-logo.png', + 'Symfony' + ) + ) + ) + ->block(new SlackDividerBlock()) + ->block($contributeToSymfonyBlocks); + + // Add the custom options to the chat message and send the message + $chatMessage->options($slackOptions); + + $chatter->send($chatMessage); + +.. _`Block elements`: https://api.slack.com/reference/block-kit/block-elements diff --git a/notifier/texters.rst b/notifier/texters.rst new file mode 100644 index 00000000000..12505cacfa1 --- /dev/null +++ b/notifier/texters.rst @@ -0,0 +1,41 @@ +.. index:: + single: Notifier; Texters + +How to send SMS Messages +======================== + +.. versionadded:: 5.0 + + The Notifier component was introduced in Symfony 5.0 as an + :doc:`experimental feature `. + +The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows +you to sent SMS messages:: + + // src/Controller/SecurityController.php + namespace App\Controller; + + class SecurityController + { + /** + * @Route("/login/success") + */ + public function loginSuccess(TexterInterface $texter) + { + $sms = new SmsMessage( + // the phone number to send the SMS message to + '+1411111111', + // the message + 'A new login was detected!' + ); + + $texter->send($sms); + + // ... + } + } + +.. seealso:: + + Read :ref:`the main Notifier guide ` to see how + to configure the different transports. From 69f333022e9f46cbddb99a1af9dee1adef79c45b Mon Sep 17 00:00:00 2001 From: Wouter J Date: Wed, 5 Feb 2020 11:18:24 +0100 Subject: [PATCH 6/6] Improved some grammar thanks to @savvasal Co-Authored-By: Savvas Alexandrou --- notifier.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/notifier.rst b/notifier.rst index 741529fbf2f..8bae301a2ec 100644 --- a/notifier.rst +++ b/notifier.rst @@ -31,8 +31,8 @@ The notifier component supports the following channels: * `SMS `_ sends notifications to phones via SMS messages * `Chat `_ sends notifications to chat services like Slack and Telegram; -* `Email `_ integrating the :doc:`Symfony Mailer `; -* Browser using :ref:`flash messages `. +* `Email `_ integrates the :doc:`Symfony Mailer `; +* Browser uses :ref:`flash messages `. .. tip::