[Mailer] Add a comment to avoid the same wrong PR over and over again

fabpot · fabpot · commit c695695368e7 · 2022-07-24T18:05:20.000+02:00
diff --git a/src/Symfony/Component/Mailer/Mailer.php b/src/Symfony/Component/Mailer/Mailer.php
@@ -48,6 +48,11 @@ public function send(RawMessage $message, Envelope $envelope = null): void
         }
 
         if (null !== $this->dispatcher) {
+            // The dispatched event here has `queued` set to `true`; the goal is NOT to render the message, but to let
+            // listeners do something before a message is sent to the queue.
+            // We are using a cloned message as we still want to dispatch the **original** message, not the one modified by listeners.
+            // That's because the listeners will run again when the email is sent via Messenger by the transport (see `AbstractTransport`).
+            // Listeners should act depending on the `$queued` argument of the `MessageEvent` instance.
             $clonedMessage = clone $message;
             $clonedEnvelope = null !== $envelope ? clone $envelope : Envelope::create($clonedMessage);
             $event = new MessageEvent($clonedMessage, $clonedEnvelope, (string) $this->transport, true);
