diff --git a/_build/redirection_map b/_build/redirection_map index 764f690c213..c58e85b6c23 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -540,3 +540,6 @@ /components/yaml/yaml_format /components/yaml#yaml-format /components/expression_language/syntax /components/expression_language#expression-language-syntax /components/expression_language/extending /components/expression_language#expression-language-extending +/notifier/chatters /notifier#sending-chat-messages +/notifier/texters /notifier#sending-sms +/notifier/events /notifier#notifier-events diff --git a/notifier.rst b/notifier.rst index 4455fb563dc..0590c5ae4b6 100644 --- a/notifier.rst +++ b/notifier.rst @@ -46,7 +46,6 @@ The notifier component supports the following channels: API's tokens. .. _notifier-sms-channel: -.. _notifier-texter-dsn: SMS Channel ~~~~~~~~~~~ @@ -169,8 +168,47 @@ configure the ``texter_transports``: ; }; +.. _sending-sms: + +The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows you to +send SMS messages:: + + // src/Controller/SecurityController.php + namespace App\Controller; + + use Symfony\Component\Notifier\Message\SmsMessage; + use Symfony\Component\Notifier\TexterInterface; + use Symfony\Component\Routing\Annotation\Route; + + 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!' + ); + + $sentMessage = $texter->send($sms); + + // ... + } + } + +The ``send()`` method returns a variable of type +:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides +information such as the message ID and the original message contents. + +.. versionadded:: 5.2 + + The ``SentMessage`` class was introduced in Symfony 5.2. + .. _notifier-chat-channel: -.. _notifier-chatter-dsn: Chat Channel ~~~~~~~~~~~~ @@ -186,24 +224,24 @@ 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 -============== ==================================== ============================================================================= -AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION`` -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`` -Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID`` -GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY`` -LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default`` -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`` -Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL`` -============== ==================================== ============================================================================= +====================================== ==================================== ============================================================================= +Service Package DSN +====================================== ==================================== ============================================================================= +AmazonSns ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION`` +:doc:`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`` +Gitter ``symfony/gitter-notifier`` ``gitter://TOKEN@default?room_id=ROOM_ID`` +GoogleChat ``symfony/google-chat-notifier`` ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?thread_key=THREAD_KEY`` +LinkedIn ``symfony/linked-in-notifier`` ``linkedin://TOKEN:USER_ID@default`` +Mattermost ``symfony/mattermost-notifier`` ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL`` +Mercure ``symfony/mercure-notifier`` ``mercure://HUB_ID?topic=TOPIC`` +:doc:`MicrosoftTeams ` ``symfony/microsoft-teams-notifier`` ``microsoftteams://default/PATH`` +RocketChat ``symfony/rocket-chat-notifier`` ``rocketchat://TOKEN@ENDPOINT?channel=CHANNEL`` +:doc:`Slack ` ``symfony/slack-notifier`` ``slack://TOKEN@default?channel=CHANNEL`` +:doc:`Telegram ` ``symfony/telegram-notifier`` ``telegram://TOKEN@default?channel=CHAT_ID`` +Zulip ``symfony/zulip-notifier`` ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL`` +====================================== ==================================== ============================================================================= .. versionadded:: 5.1 @@ -273,6 +311,41 @@ Chatters are configured using the ``chatter_transports`` setting: ; }; +.. _sending-chat-messages: + +The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows +you to send messages to chat services:: + + // src/Controller/CheckoutController.php + namespace App\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; + use Symfony\Component\Notifier\ChatterInterface; + use Symfony\Component\Notifier\Message\ChatMessage; + use Symfony\Component\Routing\Annotation\Route; + + 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'); + + $sentMessage = $chatter->send($message); + + // ... + } + } + +The ``send()`` method returns a variable of type +:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides +information such as the message ID and the original message contents. + .. _notifier-email-channel: Email Channel @@ -750,18 +823,90 @@ all configured texter and chatter transports only in the ``dev`` (and/or chatter_transports: slack: 'null://null' +.. _notifier-events: + +.. index:: + single: Notifier; Events + +Using Events +------------ + +.. versionadded:: 5.4 + + The ``MessageEvent``, ``FailedMessageEvent`` and ``SentMessageEvent`` were + introduced in Symfony 5.4. + +The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component +allows you to optionally hook into the lifecycle via events. + +The ``MessageEvent::class`` Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Typical Purposes**: Doing something before the message is send (like logging +which message is going to be send, or displaying something about the event +to be executed. + +Just before send the message, the event class ``MessageEvent`` is +dispatched. Listeners receive a +:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event:: + + use Symfony\Component\Notifier\Event\MessageEvent; + + $dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) { + // gets the message instance + $message = $event->getMessage(); + + // log something + $this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()')); + }); + +The ``FailedMessageEvent`` Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Typical Purposes**: Doing something before the exception is thrown (Retry to send the message or log additional information). + +Whenever an exception is thrown while sending the message, the event class ``FailedMessageEvent`` is +dispatched. A listener can do anything useful before the exception is thrown. + +Listeners receive a +:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event:: + + use Symfony\Component\Notifier\Event\FailedMessageEvent; + + $dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) { + // gets the message instance + $message = $event->getMessage(); + + // gets the error instance + $error = $event->getError(); + + // log something + $this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()')); + }); + +The ``SentMessageEvent`` Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Typical Purposes**: To perform some action when the message is successfully sent (like retrieve the id returned +when the message is sent). + +After the message has been successfully sent, the event class ``SentMessageEvent`` is +dispatched. Listeners receive a +:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event:: + + use Symfony\Component\Notifier\Event\SentMessageEvent; + + $dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) { + // gets the message instance + $message = $event->getOriginalMessage(); + + // log something + $this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()')); + }); + .. TODO .. - Using the message bus for asynchronous notification .. - Describe notifier monolog handler .. - Describe notification_on_failed_messages integration -Learn more ----------- - -.. toctree:: - :maxdepth: 1 - :glob: - - notifier/* - .. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt diff --git a/notifier/chatters.rst b/notifier/chatters.rst deleted file mode 100644 index bc1a4da1914..00000000000 --- a/notifier/chatters.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. index:: - single: Notifier; Chatters - -How to send Chat Messages -========================= - -.. versionadded:: 5.0 - - The Notifier component was introduced in Symfony 5.0. - -The :class:`Symfony\\Component\\Notifier\\ChatterInterface` class allows -you to send messages to chat services like Slack or Telegram:: - - // src/Controller/CheckoutController.php - namespace App\Controller; - - use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; - use Symfony\Component\Notifier\ChatterInterface; - use Symfony\Component\Notifier\Message\ChatMessage; - use Symfony\Component\Routing\Annotation\Route; - - 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'); - - $sentMessage = $chatter->send($message); - - // ... - } - } - -The ``send()`` method returns a variable of type -:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides -information such as the message ID and the original message contents. - -.. versionadded:: 5.2 - - The ``SentMessage`` class was introduced in Symfony 5.2. - -.. 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` class -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\SlackImageBlockElement; - 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://symfony.com/favicons/apple-touch-icon.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); - -Adding Fields and Values to a Slack Message -------------------------------------------- - -To add fields and values to your message you can use the -:method:`SlackSectionBlock::field() ` method:: - - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; - use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage('Symfony Feature'); - - $options = (new SlackOptions()) - ->block((new SlackSectionBlock())->text('My message')) - ->block(new SlackDividerBlock()) - ->block( - (new SlackSectionBlock()) - ->field('*Max Rating*') - ->field('5.0') - ->field('*Min Rating*') - ->field('1.0') - ); - - // Add the custom options to the chat message and send the message - $chatMessage->options($options); - - $chatter->send($chatMessage); - -The result will be something like: - -.. image:: /_images/notifier/slack/field-method.png - :align: center - -.. versionadded:: 5.1 - - The `field()` method was introduced in Symfony 5.1. - -Adding a Header to a Slack Message ----------------------------------- - -To add a header to your message use the -:class:`Symfony\\Component\\Notifier\\Bridge\\Slack\\Block\\SlackHeaderBlock` class:: - - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackHeaderBlock; - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; - use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage('Symfony Feature'); - - $options = (new SlackOptions()) - ->block((new SlackHeaderBlock('My Header'))) - ->block((new SlackSectionBlock())->text('My message')) - ->block(new SlackDividerBlock()) - ->block( - (new SlackSectionBlock()) - ->field('*Max Rating*') - ->field('5.0') - ->field('*Min Rating*') - ->field('1.0') - ); - - // Add the custom options to the chat message and send the message - $chatMessage->options($options); - - $chatter->send($chatMessage); - -The result will be something like: - -.. image:: /_images/notifier/slack/slack-header.png - :align: center - -.. versionadded:: 5.3 - - The ``SlackHeaderBlock`` class was introduced in Symfony 5.3. - -Adding a Footer to a Slack Message ----------------------------------- - -To add a footer to your message use the -:class:`Symfony\\Component\\Notifier\\Bridge\\Slack\\Block\\SlackContextBlock` class:: - - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackContextBlock; - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; - use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage('Symfony Feature'); - - $contextBlock = (new SlackContextBlock()) - ->text('My Context') - ->image('https://symfony.com/logos/symfony_white_03.png', 'Symfony Logo') - ; - - $options = (new SlackOptions()) - ->block((new SlackSectionBlock())->text('My message')) - ->block(new SlackDividerBlock()) - ->block( - (new SlackSectionBlock()) - ->field('*Max Rating*') - ->field('5.0') - ->field('*Min Rating*') - ->field('1.0') - ) - ->block($contextBlock) - ; - - $chatter->send($chatMessage); - -The result will be something like: - -.. image:: /_images/notifier/slack/slack-footer.png - :align: center - -.. versionadded:: 5.3 - - The ``SlackContextBlock`` class was introduced in Symfony 5.3. - -Sending a Slack Message as a Reply ----------------------------------- - -To send your slack message as a reply in a thread use the -:method:`SlackOptions::threadTs() ` method:: - - use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; - use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage('Symfony Feature'); - - $options = (new SlackOptions()) - ->block((new SlackSectionBlock())->text('My reply')) - ->threadTs('1621592155.003100') - ; - - // Add the custom options to the chat message and send the message - $chatMessage->options($options); - - $chatter->send($chatMessage); - -The result will be something like: - -.. image:: /_images/notifier/slack/message-reply.png - :align: center - -.. versionadded:: 5.3 - - The ``threadTs()`` method was introduced in Symfony 5.3. - -Adding Interactions to a Discord Message ----------------------------------------- - -With a Discord message, you can use the -:class:`Symfony\\Component\\Notifier\\Bridge\\Discord\\DiscordOptions` class -to add some interactive options called `Embed elements`_:: - - use Symfony\Component\Notifier\Bridge\Discord\DiscordOptions; - use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordEmbed; - use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordFieldEmbedObject; - use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordFooterEmbedObject; - use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordMediaEmbedObject; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage(''); - - // Create Discord Embed - $discordOptions = (new DiscordOptions()) - ->username('connor bot') - ->addEmbed((new DiscordEmbed()) - ->color(2021216) - ->title('New song added!') - ->thumbnail((new DiscordMediaEmbedObject()) - ->url('https://i.scdn.co/image/ab67616d0000b2735eb27502aa5cb1b4c9db426b')) - ->addField((new DiscordFieldEmbedObject()) - ->name('Track') - ->value('[Common Ground](https://open.spotify.com/track/36TYfGWUhIRlVjM8TxGUK6)') - ->inline(true) - ) - ->addField((new DiscordFieldEmbedObject()) - ->name('Artist') - ->value('Alasdair Fraser') - ->inline(true) - ) - ->addField((new DiscordFieldEmbedObject()) - ->name('Album') - ->value('Dawn Dance') - ->inline(true) - ) - ->footer((new DiscordFooterEmbedObject()) - ->text('Added ...') - ->iconUrl('https://upload.wikimedia.org/wikipedia/commons/thumb/1/19/Spotify_logo_without_text.svg/200px-Spotify_logo_without_text.svg.png') - ) - ) - ; - - // Add the custom options to the chat message and send the message - $chatMessage->options($discordOptions); - - $chatter->send($chatMessage); - -Adding Interactions to a Telegram Message ------------------------------------------ - -With a Telegram message, you can use the -:class:`Symfony\\Component\\Notifier\\Bridge\\Telegram\\TelegramOptions` class -to add `message options`_:: - - use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\Button\InlineKeyboardButton; - use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\InlineKeyboardMarkup; - use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage(''); - - // Create Telegram options - $telegramOptions = (new TelegramOptions()) - ->chatId('@symfonynotifierdev') - ->parseMode('MarkdownV2') - ->disableWebPagePreview(true) - ->disableNotification(true) - ->replyMarkup((new InlineKeyboardMarkup()) - ->inlineKeyboard([ - (new InlineKeyboardButton('Visit symfony.com')) - ->url('https://symfony.com/'), - ]) - ); - - // Add the custom options to the chat message and send the message - $chatMessage->options($telegramOptions); - - $chatter->send($chatMessage); - -Adding text to a Microsoft Teams Message ----------------------------------------- - -With a Microsoft Teams, you can use the ChatMessage class:: - - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\MicrosoftTeamsTransport; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = (new ChatMessage('Contribute To Symfony'))->transport('microsoftteams'); - $chatter->send($chatMessage); - -The result will be something like: - -.. image:: /_images/notifier/microsoft_teams/message.png - :align: center - -Adding Interactions to a Microsoft Teams Message ------------------------------------------------- - -With a Microsoft Teams Message, you can use the -:class:`Symfony\\Component\\Notifier\\Bridge\\MicrosoftTeams\\MicrosoftTeamsOptions` class -to add `MessageCard options`_:: - - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\ActionCard; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\HttpPostAction; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\Input\DateInput; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\Input\TextInput; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\MicrosoftTeamsOptions; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\MicrosoftTeamsTransport; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Section\Field\Fact; - use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Section\Section; - use Symfony\Component\Notifier\Message\ChatMessage; - - $chatMessage = new ChatMessage(''); - - // Action elements - $input = new TextInput(); - $input->id('input_title'); - $input->isMultiline(true)->maxLength(5)->title('In a few words, why would you like to participate?'); - - $inputDate = new DateInput(); - $inputDate->title('Proposed date')->id('input_date'); - - // Create Microsoft Teams MessageCard - $microsoftTeamsOptions = (new MicrosoftTeamsOptions()) - ->title('Symfony Online Meeting') - ->text('Symfony Online Meeting are the events where the best developers meet to share experiences...') - ->summary('Summary') - ->themeColor('#F4D35E') - ->section((new Section()) - ->title('Talk about Symfony 5.3 - would you like to join? Please give a shout!') - ->fact((new Fact()) - ->name('Presenter') - ->value('Fabien Potencier') - ) - ->fact((new Fact()) - ->name('Speaker') - ->value('Patricia Smith') - ) - ->fact((new Fact()) - ->name('Duration') - ->value('90 min') - ) - ->fact((new Fact()) - ->name('Date') - ->value('TBA') - ) - ) - ->action((new ActionCard()) - ->name('ActionCard') - ->input($input) - ->input($inputDate) - ->action((new HttpPostAction()) - ->name('Add comment') - ->target('http://target') - ) - ) - ; - - // Add the custom options to the chat message and send the message - $chatMessage->options($microsoftTeamsOptions); - $chatter->send($chatMessage); - -The result will be something like: - -.. image:: /_images/notifier/microsoft_teams/message-card.png - :align: center - -.. versionadded:: 5.4 - - Options for Microsoft Teams were introduced in Symfony 5.4. - -.. _`Block elements`: https://api.slack.com/reference/block-kit/block-elements -.. _`Embed elements`: https://discord.com/developers/docs/resources/webhook -.. _`message options`: https://core.telegram.org/bots/api -.. _`MessageCard options`: https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference diff --git a/notifier/discord.rst b/notifier/discord.rst new file mode 100644 index 00000000000..a754b69bd74 --- /dev/null +++ b/notifier/discord.rst @@ -0,0 +1,58 @@ +.. index:: + single: Notifier; Chatters + +Discord Notifier +================ + +Adding Interactions to a Message +-------------------------------- + +With a Discord message, you can use the +:class:`Symfony\\Component\\Notifier\\Bridge\\Discord\\DiscordOptions` class +to add some interactive options called `Embed elements`_:: + + use Symfony\Component\Notifier\Bridge\Discord\DiscordOptions; + use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordEmbed; + use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordFieldEmbedObject; + use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordFooterEmbedObject; + use Symfony\Component\Notifier\Bridge\Discord\Embeds\DiscordMediaEmbedObject; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage(''); + + // Create Discord Embed + $discordOptions = (new DiscordOptions()) + ->username('connor bot') + ->addEmbed((new DiscordEmbed()) + ->color(2021216) + ->title('New song added!') + ->thumbnail((new DiscordMediaEmbedObject()) + ->url('https://i.scdn.co/image/ab67616d0000b2735eb27502aa5cb1b4c9db426b')) + ->addField((new DiscordFieldEmbedObject()) + ->name('Track') + ->value('[Common Ground](https://open.spotify.com/track/36TYfGWUhIRlVjM8TxGUK6)') + ->inline(true) + ) + ->addField((new DiscordFieldEmbedObject()) + ->name('Artist') + ->value('Alasdair Fraser') + ->inline(true) + ) + ->addField((new DiscordFieldEmbedObject()) + ->name('Album') + ->value('Dawn Dance') + ->inline(true) + ) + ->footer((new DiscordFooterEmbedObject()) + ->text('Added ...') + ->iconUrl('https://upload.wikimedia.org/wikipedia/commons/thumb/1/19/Spotify_logo_without_text.svg/200px-Spotify_logo_without_text.svg.png') + ) + ) + ; + + // Add the custom options to the chat message and send the message + $chatMessage->options($discordOptions); + + $chatter->send($chatMessage); + +.. _`Embed elements`: https://discord.com/developers/docs/resources/webhook diff --git a/notifier/events.rst b/notifier/events.rst deleted file mode 100644 index 05a602a3bab..00000000000 --- a/notifier/events.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. index:: - single: Notifier; Events - -Using Events -============ - -.. versionadded:: 5.4 - - The ``MessageEvent``, ``FailedMessageEvent`` and ``SentMessageEvent`` were - introduced in Symfony 5.4. - -The :class:`Symfony\\Component\\Notifier\\Transport`` class of the Notifier component -allows you to optionally hook into the lifecycle via events. - -The ``MessageEvent::class`` Event ---------------------------------- - -**Typical Purposes**: Doing something before the message is send (like logging -which message is going to be send, or displaying something about the event -to be executed. - -Just before send the message, the event class ``MessageEvent`` is -dispatched. Listeners receive a -:class:`Symfony\\Component\\Notifier\\Event\\MessageEvent` event:: - - use Symfony\Component\Notifier\Event\MessageEvent; - - $dispatcher->addListener(MessageEvent::class, function (MessageEvent $event) { - // gets the message instance - $message = $event->getMessage(); - - // log something - $this->logger(sprintf('Message with subject: %s will be send to %s, $message->getSubject(), $message->getRecipientId()')); - }); - -The ``FailedMessageEvent`` Event --------------------------------- - -**Typical Purposes**: Doing something before the exception is thrown (Retry to send the message or log additional information). - -Whenever an exception is thrown while sending the message, the event class ``FailedMessageEvent`` is -dispatched. A listener can do anything useful before the exception is thrown. - -Listeners receive a -:class:`Symfony\\Component\\Notifier\\Event\\FailedMessageEvent` event:: - - use Symfony\Component\Notifier\Event\FailedMessageEvent; - - $dispatcher->addListener(FailedMessageEvent::class, function (FailedMessageEvent $event) { - // gets the message instance - $message = $event->getMessage(); - - // gets the error instance - $error = $event->getError(); - - // log something - $this->logger(sprintf('The message with subject: %s has not been sent successfully. The error is: %s, $message->getSubject(), $error->getMessage()')); - }); - - -The ``SentMessageEvent`` Event ------------------------------- - -**Typical Purposes**: To perform some action when the message is successfully sent (like retrieve the id returned -when the message is sent). - -After the message has been successfully sent, the event class ``SentMessageEvent`` is -dispatched. Listeners receive a -:class:`Symfony\\Component\\Notifier\\Event\\SentMessageEvent` event:: - - use Symfony\Component\Notifier\Event\SentMessageEvent; - - $dispatcher->addListener(SentMessageEvent::class, function (SentMessageEvent $event) { - // gets the message instance - $message = $event->getOriginalMessage(); - - // log something - $this->logger(sprintf('The message has been successfully sent and have id: %s, $message->getMessageId()')); - }); diff --git a/notifier/slack.rst b/notifier/slack.rst new file mode 100644 index 00000000000..fddeb3a4080 --- /dev/null +++ b/notifier/slack.rst @@ -0,0 +1,206 @@ +.. index:: + single: Notifier; Chatters + +Slack Notifier +============== + +Adding Interactions to a Message +-------------------------------- + +With a Slack message, you can use the +:class:`Symfony\\Component\\Notifier\\Bridge\\Slack\\SlackOptions` class +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\SlackImageBlockElement; + 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://symfony.com/favicons/apple-touch-icon.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); + +Adding Fields and Values to a Message +------------------------------------- + +To add fields and values to your message you can use the +:method:`SlackSectionBlock::field() ` method:: + + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; + use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage('Symfony Feature'); + + $options = (new SlackOptions()) + ->block((new SlackSectionBlock())->text('My message')) + ->block(new SlackDividerBlock()) + ->block( + (new SlackSectionBlock()) + ->field('*Max Rating*') + ->field('5.0') + ->field('*Min Rating*') + ->field('1.0') + ); + + // Add the custom options to the chat message and send the message + $chatMessage->options($options); + + $chatter->send($chatMessage); + +The result will be something like: + +.. image:: /_images/notifier/slack/field-method.png + :align: center + +.. versionadded:: 5.1 + + The `field()` method was introduced in Symfony 5.1. + +Adding a Header to a Message +---------------------------- + +To add a header to your message use the +:class:`Symfony\\Component\\Notifier\\Bridge\\Slack\\Block\\SlackHeaderBlock` class:: + + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackHeaderBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; + use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage('Symfony Feature'); + + $options = (new SlackOptions()) + ->block((new SlackHeaderBlock('My Header'))) + ->block((new SlackSectionBlock())->text('My message')) + ->block(new SlackDividerBlock()) + ->block( + (new SlackSectionBlock()) + ->field('*Max Rating*') + ->field('5.0') + ->field('*Min Rating*') + ->field('1.0') + ); + + // Add the custom options to the chat message and send the message + $chatMessage->options($options); + + $chatter->send($chatMessage); + +The result will be something like: + +.. image:: /_images/notifier/slack/slack-header.png + :align: center + +.. versionadded:: 5.3 + + The ``SlackHeaderBlock`` class was introduced in Symfony 5.3. + +Adding a Footer to a Message +---------------------------- + +To add a footer to your message use the +:class:`Symfony\\Component\\Notifier\\Bridge\\Slack\\Block\\SlackContextBlock` class:: + + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackContextBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackDividerBlock; + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; + use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage('Symfony Feature'); + + $contextBlock = (new SlackContextBlock()) + ->text('My Context') + ->image('https://symfony.com/logos/symfony_white_03.png', 'Symfony Logo') + ; + + $options = (new SlackOptions()) + ->block((new SlackSectionBlock())->text('My message')) + ->block(new SlackDividerBlock()) + ->block( + (new SlackSectionBlock()) + ->field('*Max Rating*') + ->field('5.0') + ->field('*Min Rating*') + ->field('1.0') + ) + ->block($contextBlock) + ; + + $chatter->send($chatMessage); + +The result will be something like: + +.. image:: /_images/notifier/slack/slack-footer.png + :align: center + +.. versionadded:: 5.3 + + The ``SlackContextBlock`` class was introduced in Symfony 5.3. + +Sending a Message as a Reply +---------------------------- + +To send your slack message as a reply in a thread use the +:method:`SlackOptions::threadTs() ` method:: + + use Symfony\Component\Notifier\Bridge\Slack\Block\SlackSectionBlock; + use Symfony\Component\Notifier\Bridge\Slack\SlackOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage('Symfony Feature'); + + $options = (new SlackOptions()) + ->block((new SlackSectionBlock())->text('My reply')) + ->threadTs('1621592155.003100') + ; + + // Add the custom options to the chat message and send the message + $chatMessage->options($options); + + $chatter->send($chatMessage); + +The result will be something like: + +.. image:: /_images/notifier/slack/message-reply.png + :align: center + +.. versionadded:: 5.3 + + The ``threadTs()`` method was introduced in Symfony 5.3. + +.. _`Block elements`: https://api.slack.com/reference/block-kit/block-elements diff --git a/notifier/teams.rst b/notifier/teams.rst new file mode 100644 index 00000000000..c2756d6baba --- /dev/null +++ b/notifier/teams.rst @@ -0,0 +1,99 @@ +.. index:: + single: Notifier; Chatters + +Microsoft Teams Notifier +======================== + +Adding text to a Message +------------------------ + +With a Microsoft Teams, you can use the ChatMessage class:: + + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\MicrosoftTeamsTransport; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = (new ChatMessage('Contribute To Symfony'))->transport('microsoftteams'); + $chatter->send($chatMessage); + +The result will be something like: + +.. image:: /_images/notifier/microsoft_teams/message.png + :align: center + +Adding Interactions to a Message +-------------------------------- + +With a Microsoft Teams Message, you can use the +:class:`Symfony\\Component\\Notifier\\Bridge\\MicrosoftTeams\\MicrosoftTeamsOptions` class +to add `MessageCard options`_:: + + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\ActionCard; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\HttpPostAction; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\Input\DateInput; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Action\Input\TextInput; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\MicrosoftTeamsOptions; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\MicrosoftTeamsTransport; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Section\Field\Fact; + use Symfony\Component\Notifier\Bridge\MicrosoftTeams\Section\Section; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage(''); + + // Action elements + $input = new TextInput(); + $input->id('input_title'); + $input->isMultiline(true)->maxLength(5)->title('In a few words, why would you like to participate?'); + + $inputDate = new DateInput(); + $inputDate->title('Proposed date')->id('input_date'); + + // Create Microsoft Teams MessageCard + $microsoftTeamsOptions = (new MicrosoftTeamsOptions()) + ->title('Symfony Online Meeting') + ->text('Symfony Online Meeting are the events where the best developers meet to share experiences...') + ->summary('Summary') + ->themeColor('#F4D35E') + ->section((new Section()) + ->title('Talk about Symfony 5.3 - would you like to join? Please give a shout!') + ->fact((new Fact()) + ->name('Presenter') + ->value('Fabien Potencier') + ) + ->fact((new Fact()) + ->name('Speaker') + ->value('Patricia Smith') + ) + ->fact((new Fact()) + ->name('Duration') + ->value('90 min') + ) + ->fact((new Fact()) + ->name('Date') + ->value('TBA') + ) + ) + ->action((new ActionCard()) + ->name('ActionCard') + ->input($input) + ->input($inputDate) + ->action((new HttpPostAction()) + ->name('Add comment') + ->target('http://target') + ) + ) + ; + + // Add the custom options to the chat message and send the message + $chatMessage->options($microsoftTeamsOptions); + $chatter->send($chatMessage); + +The result will be something like: + +.. image:: /_images/notifier/microsoft_teams/message-card.png + :align: center + +.. versionadded:: 5.4 + + Options for Microsoft Teams were introduced in Symfony 5.4. + +.. _`MessageCard options`: https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference diff --git a/notifier/telegram.rst b/notifier/telegram.rst new file mode 100644 index 00000000000..a76f8a9063f --- /dev/null +++ b/notifier/telegram.rst @@ -0,0 +1,39 @@ +.. index:: + single: Notifier; Chatters + +Telegram Notifier +================= + +Adding Interactions to a Message +-------------------------------- + +With a Telegram message, you can use the +:class:`Symfony\\Component\\Notifier\\Bridge\\Telegram\\TelegramOptions` class +to add `message options`_:: + + use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\Button\InlineKeyboardButton; + use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\InlineKeyboardMarkup; + use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions; + use Symfony\Component\Notifier\Message\ChatMessage; + + $chatMessage = new ChatMessage(''); + + // Create Telegram options + $telegramOptions = (new TelegramOptions()) + ->chatId('@symfonynotifierdev') + ->parseMode('MarkdownV2') + ->disableWebPagePreview(true) + ->disableNotification(true) + ->replyMarkup((new InlineKeyboardMarkup()) + ->inlineKeyboard([ + (new InlineKeyboardButton('Visit symfony.com')) + ->url('https://symfony.com/'), + ]) + ); + + // Add the custom options to the chat message and send the message + $chatMessage->options($telegramOptions); + + $chatter->send($chatMessage); + +.. _`message options`: https://core.telegram.org/bots/api diff --git a/notifier/texters.rst b/notifier/texters.rst deleted file mode 100644 index 4cf9b6f2de2..00000000000 --- a/notifier/texters.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. index:: - single: Notifier; Texters - -How to send SMS Messages -======================== - -.. versionadded:: 5.0 - - The Notifier component was introduced in Symfony 5.0. - -The :class:`Symfony\\Component\\Notifier\\TexterInterface` class allows -you to send SMS messages:: - - // src/Controller/SecurityController.php - namespace App\Controller; - - use Symfony\Component\Notifier\Message\SmsMessage; - use Symfony\Component\Notifier\TexterInterface; - use Symfony\Component\Routing\Annotation\Route; - - 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!' - ); - - $sentMessage = $texter->send($sms); - - // ... - } - } - -The ``send()`` method returns a variable of type -:class:`Symfony\\Component\\Notifier\\Message\\SentMessage` which provides -information such as the message ID and the original message contents. - -.. versionadded:: 5.2 - - The ``SentMessage`` class was introduced in Symfony 5.2. - -.. seealso:: - - Read :ref:`the main Notifier guide ` to see how - to configure the different transports.