Apr 16, 2018 · Mar 14, 2018 · Mar 18, 2018 · Mar 23, 2018 · Mar 23, 2018 · Mar 27, 2018
diff --git a/_images/components/messenger/overview.png b/_images/components/messenger/overview.png
diff --git a/components/messenger.rst b/components/messenger.rst
 .. index::
   single: Messenger
   single: Components; Messenger

 The Messenger Component
 =======================

    The Messenger component helps applications send and receive messages to/from other applications or via message queues.

 Installation
 ------------

 .. code-block:: terminal

    $ composer require symfony/messenger

 Alternatively, you can clone the `<https://github.com/symfony/messenger>`_ repository.

 .. include:: /components/require_autoload.rst.inc

 Concepts
 --------

 .. image:: /_images/components/messenger/overview.png

 **Sender**:
   Responsible for serializing and sending messages to _something_. This
   something can be a message broker or a third party API for example.

 **Receiver**:
   Responsible for deserializing and forwarding messages to handler(s). This
   can be a message queue puller or an API endpoint for example.

 **Handler**:
   Responsible for handling messages using the business logic applicable to the messages.

 Bus
 ---

 The bus is used to dispatch messages. The behaviour of the bus is in its ordered
 middleware stack. The component comes with a set of middleware that you can use.

 When using the message bus with Symfony's FrameworkBundle, the following middleware
 are configured for you:

 #. ``LoggingMiddleware`` (logs the processing of your messages)
 #. ``SendMessageMiddleware`` (enables asynchronous processing)
 #. ``HandleMessageMiddleware`` (calls the registered handle)

 Example::

    use App\Message\MyMessage;
    use Symfony\Component\Messenger\MessageBus;
    use Symfony\Component\Messenger\HandlerLocator;
    use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;

    $bus = new MessageBus([
        new HandleMessageMiddleware(new HandlerLocator([
            MyMessage::class => $handler,
        ])),
    ]);

    $result = $bus->handle(new MyMessage(/* ... */));

 .. note:

    Every middleware needs to implement the ``MiddlewareInterface`` interface.

 Handlers
 --------

 Once dispatched to the bus, messages will be handled by a "message handler". A
 message handler is a PHP callable (i.e. a function or an instance of a class)
 that will do the required processing for your message::

    namespace App\MessageHandler;

    use App\Message\MyMessage;

    class MyMessageHandler
    {
       public function __invoke(MyMessage $message)
       {
           // Message processing...
       }
    }

 Adapters
 --------

 In order to send and receive messages, you will have to configure an adapter. An
 adapter will be responsible of communicating with your message broker or 3rd parties.

 Your own sender
 ~~~~~~~~~~~~~~~

 Using the ``SenderInterface``, you can easily create your own message sender.
 Let's say you already have an ``ImportantAction`` message going through the
 message bus and handled by a handler. Now, you also want to send this message as
 an email.

 First, create your sender::

    namespace App\MessageSender;

    use App\Message\ImportantAction;
    use Symfony\Component\Message\SenderInterface;

    class ImportantActionToEmailSender implements SenderInterface
    {
       private $toEmail;
       private $mailer;

       public function __construct(\Swift_Mailer $mailer, string $toEmail)
       {
           $this->mailer = $mailer;
           $this->toEmail = $toEmail;
       }

       public function send($message)
       {
           if (!$message instanceof ImportantAction) {
               throw new \InvalidArgumentException(sprintf('Producer only supports "%s" messages.', ImportantAction::class));
           }

           $this->mailer->send(
               (new \Swift_Message('Important action made'))
                   ->setTo($this->toEmail)
                   ->setBody(
                       '<h1>Important action</h1><p>Made by '.$message->getUsername().'</p>',
                       'text/html'
                   )
           );
       }
    }

 Your own receiver
 ~~~~~~~~~~~~~~~~~

 A receiver is responsible for receiving messages from a source and dispatching
 them to the application.

 Let's say you already processed some "orders" in your application using a
 ``NewOrder`` message. Now you want to integrate with a 3rd party or a legacy
 application but you can't use an API and need to use a shared CSV file with new
 orders.

 You will read this CSV file and dispatch a ``NewOrder`` message. All you need to
 do is to write your custom CSV receiver and Symfony will do the rest.

 First, create your receiver::

    namespace App\MessageReceiver;

    use App\Message\NewOrder;
    use Symfony\Component\Message\ReceiverInterface;
    use Symfony\Component\Serializer\SerializerInterface;

    class NewOrdersFromCsvFile implements ReceiverInterface
    {
       private $serializer;
       private $filePath;

       public function __construct(SerializerInteface $serializer, string $filePath)
       {
           $this->serializer = $serializer;
           $this->filePath = $filePath;
       }

       public function receive(callable $handler) : void
       {
           $ordersFromCsv = $this->serializer->deserialize(file_get_contents($this->filePath), 'csv');

           foreach ($ordersFromCsv as $orderFromCsv) {
               $handler(new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']));
           }
       }

       public function stop(): void
       {
           // noop
       }
    }

 Receiver and Sender on the same bus
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 To allow us to receive and send messages on the same bus and prevent an infinite
 loop, the message bus is equipped with the ``WrapIntoReceivedMessage`` middleware.
 It will wrap the received messages into ``ReceivedMessage`` objects and the
 ``SendMessageMiddleware`` middleware will know it should not route these
 messages again to an adapter.
diff --git a/index.rst b/index.rst
    frontend
    http_cache
    logging
    messenger
    performance
    profiler
    routing
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,192 @@
		.. index::
		single: Messenger
		single: Components; Messenger

		The Messenger Component
		=======================

		The Messenger component helps applications send and receive messages to/from other applications or via message queues.
Copy link boiteMar 29, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. - The Messenger component helps applications send and receive messages to/from other applications or via message queues.+ The Messenger component helps applications send messages to and receive messages from other applications and via message queues. sroze and grisha-chasovskih reacted with thumbs down emoji

		Installation
		------------

		.. code-block:: terminal

		$ composer require symfony/messenger

		Alternatively, you can clone the `<https://github.com/symfony/messenger>`_ repository.

		.. include:: /components/require_autoload.rst.inc

		Concepts
		--------

		.. image:: /_images/components/messenger/overview.png

		Sender:
		Responsible for serializing and sending messages to _something_. This
		something can be a message broker or a third party API for example.

		Receiver:
		Responsible for deserializing and forwarding messages to handler(s). This
		can be a message queue puller or an API endpoint for example.

		Handler:
		Responsible for handling messages using the business logic applicable to the messages.

		Bus
		---

		The bus is used to dispatch messages. The behaviour of the bus is in its ordered
		middleware stack. The component comes with a set of middleware that you can use.

		When using the message bus with Symfony's FrameworkBundle, the following middleware
		are configured for you:

		#. ``LoggingMiddleware`` (logs the processing of your messages)
		#. ``SendMessageMiddleware`` (enables asynchronous processing)
		#. ``HandleMessageMiddleware`` (calls the registered handle)

		Example::

		use App\Message\MyMessage;
		use Symfony\Component\Messenger\MessageBus;
		use Symfony\Component\Messenger\HandlerLocator;
		use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;

		$bus = new MessageBus([
		new HandleMessageMiddleware(new HandlerLocator([
		MyMessage::class => $handler,
		])),
		]);

		$result = $bus->handle(new MyMessage(/* ... */));

		.. note:

		Every middleware needs to implement the ``MiddlewareInterface`` interface.

		Handlers
		--------

		Once dispatched to the bus, messages will be handled by a "message handler". A
Copy link boiteMar 29, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. "dispatched" is confusing here: according to the Bus section, the bus is responsible for dispatching messages; and the method used to get a message on to the bus is`handle()`. Copy link ContributorAuthor srozeApr 12, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. No, it's`dispatch` :)
		message handler is a PHP callable (i.e. a function or an instance of a class)
Copy link Contributor theofidryMar 30, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. we could add a link to the official doc here: callable:https://secure.php.net/manual/en/language.types.callable.php anonymous function:https://secure.php.net/manual/en/functions.anonymous.php an invokable class:https://secure.php.net/manual/en/language.oop5.magic.php#object.invoke OskarStark and grisha-chasovskih reacted with thumbs up emoji
		that will do the required processing for your message::

		namespace App\MessageHandler;

		use App\Message\MyMessage;

		class MyMessageHandler
		{
		public function __invoke(MyMessage $message)
		{
		// Message processing...
		}
		}

		Adapters
		--------

		In order to send and receive messages, you will have to configure an adapter. An
		adapter will be responsible of communicating with your message broker or 3rd parties.

		Your own sender
		~~~~~~~~~~~~~~~

		Using the ``SenderInterface``, you can easily create your own message sender.
		Let's say you already have an ``ImportantAction`` message going through the
		message bus and handled by a handler. Now, you also want to send this message as
		an email.

		First, create your sender::

		namespace App\MessageSender;

		use App\Message\ImportantAction;
		use Symfony\Component\Message\SenderInterface;

		class ImportantActionToEmailSender implements SenderInterface
		{
		private $toEmail;
		private $mailer;

		public function __construct(\Swift_Mailer $mailer, string $toEmail)
		{
		$this->mailer = $mailer;
		$this->toEmail = $toEmail;
		}

		public function send($message)
		{
		if (!$message instanceof ImportantAction) {
		throw new \InvalidArgumentException(sprintf('Producer only supports "%s" messages.', ImportantAction::class));
Copy link Contributor greg0ireMar 27, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I would linebreak this, but again not sure what the norm is in Symfony. I know you guys don't like linebreaks, but maybe it's different for docs? Since you might want to avoid the wrapping
		}

		$this->mailer->send(
		(new \Swift_Message('Important action made'))
		->setTo($this->toEmail)
		->setBody(
		'<h1>Important action</h1><p>Made by '.$message->getUsername().'</p>',
		'text/html'
		)
		);
		}
		}

		Your own receiver
		~~~~~~~~~~~~~~~~~

		A receiver is responsible for receiving messages from a source and dispatching
		them to the application.

		Let's say you already processed some "orders" in your application using a
		``NewOrder`` message. Now you want to integrate with a 3rd party or a legacy
		application but you can't use an API and need to use a shared CSV file with new
		orders.

		You will read this CSV file and dispatch a ``NewOrder`` message. All you need to
		do is to write your custom CSV receiver and Symfony will do the rest.

		First, create your receiver::

		namespace App\MessageReceiver;

		use App\Message\NewOrder;
		use Symfony\Component\Message\ReceiverInterface;
		use Symfony\Component\Serializer\SerializerInterface;

		class NewOrdersFromCsvFile implements ReceiverInterface
		{
		private $serializer;
		private $filePath;

		public function __construct(SerializerInteface $serializer, string $filePath)
		{
		$this->serializer = $serializer;
		$this->filePath = $filePath;
		}

		public function receive(callable $handler) : void
		{
		$ordersFromCsv = $this->serializer->deserialize(file_get_contents($this->filePath), 'csv');

		foreach ($ordersFromCsv as $orderFromCsv) {
		$handler(new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']));
		}
		}

		public function stop(): void
		{
		// noop
		}
		}

		Receiver and Sender on the same bus
		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		To allow us to receive and send messages on the same bus and prevent an infinite
		loop, the message bus is equipped with the ``WrapIntoReceivedMessage`` middleware.
		It will wrap the received messages into ``ReceivedMessage`` objects and the
		``SendMessageMiddleware`` middleware will know it should not route these
		messages again to an adapter.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -41,6 +41,7 @@ Topics
		frontend
		http_cache
		logging
		messenger
		performance
		profiler
		routing
Expand Down