feat(SendIt): Add pre and post render events (#1233)

Author: burn1ngbear

src/SendIt/src/Event/PostRender.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\SendIt\Event;
+
+use Spiral\Mailer\MessageInterface;
+use Symfony\Component\Mime\Email;
+use Symfony\Contracts\EventDispatcher\Event;
+
+/**
+ * Event triggered after the email content is rendered but before it is sent.
+ *
+ * Unlike {@see PreRender}, this event is dispatched when the email has already been transformed
+ * into its final form (e.g., templates applied, HTML generated). Listeners can access the rendered
+ * content but should avoid modifying it unless necessary (e.g., adding debug headers).
+ *
+ * Typical use cases:
+ * - Logging the final email content
+ * - Adding transport-specific headers
+ * - Conditional last-minute modifications
+ *
+ * Example:
+ * ```php
+ * $dispatcher->addListener(PostRender::class, function (PostRender $event) {
+ *     $event->email->getHeaders()->addTextHeader('X-Debug', '1');
+ * });
+ * ```
+ */
+final class PostRender extends Event
+{
+    public function __construct(
+        public readonly MessageInterface $message,
+        public readonly Email            $email,
+    ) {}
+}

src/SendIt/src/Event/PreRender.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\SendIt\Event;
+
+use Spiral\Mailer\MessageInterface;
+use Symfony\Component\Mime\Email;
+use Symfony\Contracts\EventDispatcher\Event;
+
+/**
+ * Event triggered before the email content is rendered.
+ *
+ * This event allows you to modify the {@see Email} object (e.g., headers, body, or attachments)
+ * before it is passed to the mailer for sending. The original {@see MessageInterface} is provided
+ * for context but should not be modified.
+ *
+ * Example usage (listener):
+ * ```
+ * $dispatcher->addListener(PreRender::class, function (PreRender $event) {
+ *     $event->email->addHeader('X-Custom', 'value');
+ * });
+ * ```
+ */
+final class PreRender extends Event
+{
+    public function __construct(
+        public readonly MessageInterface $message,
+        public readonly Email            $email,
+    ) {}
+}

src/SendIt/src/Renderer/ViewRenderer.php

@@ -4,8 +4,11 @@
 
 namespace Spiral\SendIt\Renderer;
 
+use Psr\EventDispatcher\EventDispatcherInterface;
 use Spiral\Mailer\Exception\MailerException;
 use Spiral\Mailer\MessageInterface;
+use Spiral\SendIt\Event\PostRender;
+use Spiral\SendIt\Event\PreRender;
 use Spiral\SendIt\RendererInterface;
 use Spiral\Views\Exception\ViewException;
 use Spiral\Views\ViewsInterface;
@@ -15,6 +18,7 @@ final class ViewRenderer implements RendererInterface
 {
     public function __construct(
         private readonly ViewsInterface $views,
+        private readonly ?EventDispatcherInterface $eventDispatcher = null,
     ) {}
 
     /**
@@ -51,23 +55,26 @@ public function render(MessageInterface $message): Email
             );
         }
 
-        $msg = new Email();
+        $email = new Email();
 
         if ($message->getFrom() !== null) {
-            $msg->from($message->getFrom());
+            $email->from($message->getFrom());
         }
 
         if ($message->getReplyTo() !== null) {
-            $msg->replyTo($message->getReplyTo());
+            $email->replyTo($message->getReplyTo());
         }
 
-        $msg->to(...$message->getTo());
-        $msg->cc(...$message->getCC());
-        $msg->bcc(...$message->getBCC());
+        $email->to(...$message->getTo());
+        $email->cc(...$message->getCC());
+        $email->bcc(...$message->getBCC());
 
         try {
+            $cloneMessage = clone $message;
+            $this->eventDispatcher?->dispatch(new PreRender(message: $cloneMessage, email: $email));
             // render message partials
-            $view->render(\array_merge(['_msg_' => $msg], $message->getData()));
+            $view->render(\array_merge(['_msg_' => $email], $cloneMessage->getData()));
+            $this->eventDispatcher?->dispatch(new PostRender(message: $cloneMessage, email: $email));
         } catch (ViewException $e) {
             throw new MailerException(
                 \sprintf('Unable to render email `%s`: %s', $message->getSubject(), $e->getMessage()),
@@ -76,6 +83,6 @@ public function render(MessageInterface $message): Email
             );
         }
 
-        return $msg;
+        return $email;
     }
 }

src/SendIt/tests/ViewRendererTest.php

@@ -1,18 +1,85 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Spiral\Tests\SendIt;
 
 use PHPUnit\Framework\TestCase;
+use Spiral\Mailer\Message;
 use Spiral\Mailer\MessageInterface;
+use Spiral\SendIt\Event\PostRender;
+use Spiral\SendIt\Event\PreRender;
 use Spiral\SendIt\Renderer\ViewRenderer;
 use Spiral\Views\ViewInterface;
 use Spiral\Views\ViewsInterface;
+use Symfony\Component\EventDispatcher\Debug\TraceableEventDispatcher;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+use Symfony\Component\Stopwatch\Stopwatch;
 
 /**
  * @coversDefaultClass \Spiral\SendIt\Renderer\ViewRenderer
  */
 final class ViewRendererTest extends TestCase
 {
+    /**
+     * Checking for event hits and processing by listeners without changing the original $message
+     *
+     * @covers ::render
+     */
+    public function testRender(): void
+    {
+        $view = $this->createMock(ViewInterface::class);
+        $view->expects(self::once())->method('render');
+
+        $views = $this->createMock(ViewsInterface::class);
+        $views->expects(self::once())->method('get')->willReturn($view);
+
+        $message = new Message('subject has not been changed', 'to@mail.test');
+        $beforeHash = \spl_object_hash($message);
+
+        $eventDispatcher = new TraceableEventDispatcher(
+            new EventDispatcher(),
+            new Stopwatch(),
+        );
+
+        $eventDispatcher->addListener(PreRender::class, static function (PreRender $event): void {
+            $message = $event->message;
+            $message->setSubject('subject1');
+        });
+        $eventDispatcher->addListener(PostRender::class, static function (PostRender $event): void {
+            $event->message->setSubject('subject2');
+        });
+
+        $target = new ViewRenderer($views, $eventDispatcher);
+        $msg = $target->render($message);
+
+        $afterHash = \spl_object_hash($message);
+
+        self::assertSame($beforeHash, $afterHash);
+        self::assertSame(['To: to@mail.test'], $msg->getHeaders()->toArray());
+        self::assertCount(2, $eventDispatcher->getCalledListeners());
+        self::assertSame('subject has not been changed', $message->getSubject());
+    }
+
+    /**
+     * Health check when EventDispatcher = null.
+     *
+     * @covers ::render
+     */
+    public function testRenderWithoutDispatcher(): void
+    {
+        $view = $this->createMock(ViewInterface::class);
+        $view->expects(self::once())->method('render');
+
+        $views = $this->createMock(ViewsInterface::class);
+        $views->expects(self::once())->method('get')->willReturn($view);
+
+        $message = new Message('subject has not been changed', 'to@mail.test');
+
+        $target = new ViewRenderer($views);
+        $target->render($message);
+    }
+
     /**
      * Check that all added headers are added to the final object.
      *