feat: support headers

Author: innocenzi

packages/mailer/src/EmailToSymfonyEmailMapper.php

@@ -6,6 +6,7 @@
 
 use Symfony\Component\Mime\Address as SymfonyAddress;
 use Symfony\Component\Mime\Email as SymfonyEmail;
+use Symfony\Component\Mime\Header\Headers;
 use Tempest\Mail\Exceptions\MissingExpeditorAddressException;
 use Tempest\Mail\Exceptions\MissingRecipientAddressException;
 use Tempest\Mapper\Mapper;
@@ -37,6 +38,10 @@ public function map(mixed $from, mixed $to): SymfonyEmail
         $email = $from;
         $symfonyEmail = new SymfonyEmail();
 
+        foreach ($email->envelope->headers as $key => $value) {
+            $symfonyEmail->getHeaders()->addHeader($key, $value);
+        }
+
         if ($email->envelope->from) {
             $symfonyEmail->from(...$this->convertAddresses($email->envelope->from));
         } elseif ($this->mailerConfig->from) {

packages/mailer/src/Envelope.php

@@ -14,6 +14,7 @@ public function __construct(
         public null|string|array|Address $cc = null,
         public null|string|array|Address $bcc = null,
         public null|string|array|Address $replyTo = null,
+        public array $headers = [],
         public Priority $priority = Priority::NORMAL,
     ) {}
 }

packages/mailer/src/Testing/SentTestingEmail.php

@@ -47,7 +47,7 @@ public function assertSubjectContains(string $expect): self
     {
         Assert::assertStringContainsString(
             needle: $expect,
-            haystack: $this->symfonyEmail->getSubject(),
+            haystack: $this->symfonyEmail->getSubject() ?? '',
             message: "Failed asserting that the email's subject is `{$expect}`.",
         );
 
@@ -279,6 +279,30 @@ public function assertAttached(string $filename, ?\Closure $callback = null): se
         return $this;
     }
 
+    /**
+     * Asserts that the email has a header with the given name.
+     */
+    public function assertHasHeader(string $header, ?string $value = null): self
+    {
+        $headers = Arr\to_array($this->symfonyEmail->getHeaders()->all());
+
+        Assert::assertArrayHasKey(
+            key: mb_strtolower($header),
+            array: $headers,
+            message: sprintf('Failed asserting that the email has a header `%s`.', $header),
+        );
+
+        if ($value !== null) {
+            Assert::assertSame(
+                expected: $value,
+                actual: $headers[mb_strtolower($header)]->getBodyAsString(),
+                message: sprintf('Failed asserting that the email has a header `%s` with value `%s`.', $header, $value),
+            );
+        }
+
+        return $this;
+    }
+
     private function assertAddressListContains(null|string|array|Address $haystack, string|array $needles, string $message): self
     {
         $needles = Arr\wrap($needles);

tests/Integration/Mailer/SentEmailTest.php

@@ -26,6 +26,7 @@ private function sendTestEmail(?Envelope $envelope = null, ?Content $content = n
                 cc: ['[email protected]', '[email protected]'],
                 bcc: ['[email protected]', '[email protected]'],
                 from: '[email protected]',
+                headers: ['X-Foo' => 'bar'],
             ),
             content: $content ?? new Content(
                 text: 'Hello Jon in Text',
@@ -70,6 +71,9 @@ public function test_sent_email_assertions(): void
         $sent->assertNotFrom('[email protected]');
 
         $sent->assertPriority(Priority::NORMAL);
+
+        $sent->assertHasHeader('X-Foo');
+        $sent->assertHasHeader('X-Foo', 'bar');
     }
 
     public function test_send_to_address_vo(): void