Issue 691: Expose missing Message-ID reference headers

src/PhpImap/IncomingMailHeader.php

@@ -146,4 +146,10 @@ class IncomingMailHeader
 
     /** @var string|null */
     public $messageId;
+
+    /** @var string|null */
+    public $inReplyTo;
+
+    /** @var string|null */
+    public $references;
 }

src/PhpImap/Mailbox.php

@@ -1171,15 +1171,48 @@ public function getRawMail(int $msgId, bool $markAsSeen = true): string
      */
     public function getMailHeaderFieldValue(string $headersRaw, string $header_field_name): string
     {
-        $header_field_value = '';
+        $pattern = '/^'.\preg_quote($header_field_name, '/').':([^\r\n]*(?:\r?\n[ \t][^\r\n]*)*)/im';
 
-        if (\preg_match("/$header_field_name\:(.*)/i", $headersRaw, $matches)) {
-            if (isset($matches[1])) {
-                return \trim($matches[1]);
-            }
+        if (\preg_match($pattern, $headersRaw, $matches) && isset($matches[1]) && \is_string($matches[1])) {
+            /** @var string */
+            $headerFieldValue = \preg_replace('/\r?\n[ \t]+/', ' ', $matches[1]) ?? $matches[1];
+
+            return \trim($headerFieldValue);
         }
 
-        return $header_field_value;
+        return '';
+    }
+
+    /**
+     * @psalm-return array{messageId:null|string, inReplyTo:null|string, references:null|string}
+     */
+    protected function getThreadingHeaders(object $head, string $headersRaw): array
+    {
+        /** @var scalar|array|object|resource|null */
+        $parsedMessageId = $head->message_id ?? null;
+
+        if (null !== $parsedMessageId && !\is_string($parsedMessageId)) {
+            throw new UnexpectedValueException('Message ID was expected to be a string, '.\gettype($parsedMessageId).' found!');
+        }
+
+        $messageId = (\is_string($parsedMessageId) && '' !== \trim($parsedMessageId)) ? \trim($parsedMessageId) : $this->getOptionalMailHeaderFieldValue($headersRaw, 'Message-ID');
+
+        return [
+            'messageId' => $messageId,
+            'inReplyTo' => $this->getOptionalMailHeaderFieldValue($headersRaw, 'In-Reply-To'),
+            'references' => $this->getOptionalMailHeaderFieldValue($headersRaw, 'References'),
+        ];
+    }
+
+    protected function getOptionalMailHeaderFieldValue(string $headersRaw, string $headerFieldName): ?string
+    {
+        $headerFieldValue = $this->getMailHeaderFieldValue($headersRaw, $headerFieldName);
+
+        if ('' === $headerFieldValue) {
+            return null;
+        }
+
+        return $headerFieldValue;
     }
 
     /**
@@ -1203,6 +1236,7 @@ public function getMailHeader(int $mailId): IncomingMailHeader
          * date?:scalar,
          * Date?:scalar,
          * subject?:scalar,
+         * message_id?:scalar,
          * from?:HOSTNAMEANDADDRESS,
          * to?:HOSTNAMEANDADDRESS,
          * cc?:HOSTNAMEANDADDRESS,
@@ -1330,12 +1364,10 @@ public function getMailHeader(int $mailId): IncomingMailHeader
             }
         }
 
-        if (isset($head->message_id)) {
-            if (!\is_string($head->message_id)) {
-                throw new UnexpectedValueException('Message ID was expected to be a string, '.\gettype($head->message_id).' found!');
-            }
-            $header->messageId = $head->message_id;
-        }
+        $threadingHeaders = $this->getThreadingHeaders($head, $headersRaw);
+        $header->messageId = $threadingHeaders['messageId'];
+        $header->inReplyTo = $threadingHeaders['inReplyTo'];
+        $header->references = $threadingHeaders['references'];
 
         return $header;
     }

tests/unit/Fixtures/Mailbox.php

@@ -13,6 +13,11 @@ public function decodeRFC2231ForTests(string $string): string
         return $this->decodeRFC2231($string);
     }
 
+    public function getMailHeaderFieldValueForTests(string $headersRaw, string $headerFieldName): string
+    {
+        return $this->getMailHeaderFieldValue($headersRaw, $headerFieldName);
+    }
+
     /**
      * @return (null|string)[]|null
      */
@@ -21,6 +26,14 @@ public function possiblyGetEmailAndNameFromRecipientForTests(object $recipient):
         return $this->possiblyGetEmailAndNameFromRecipient($recipient);
     }
 
+    /**
+     * @psalm-return array{messageId:null|string, inReplyTo:null|string, references:null|string}
+     */
+    public function getThreadingHeadersForTests(object $head, string $headersRaw): array
+    {
+        return $this->getThreadingHeaders($head, $headersRaw);
+    }
+
     /**
      * @param array<int, object> $t
      *

tests/unit/MailboxHeaderParsingTest.php

@@ -0,0 +1,69 @@
+<?php
+/**
+ * Mailbox header parsing focused unit tests.
+ */
+declare(strict_types=1);
+
+namespace PhpImap;
+
+use PHPUnit\Framework\TestCase;
+use stdClass;
+
+final class MailboxHeaderParsingTest extends TestCase
+{
+    public function testGetMailHeaderFieldValueUnfoldsFoldedHeaderLines(): void
+    {
+        $headersRaw =
+            "References: <first@example.com>\r\n".
+            "\t<second@example.com>\r\n".
+            'Subject: Example'."\r\n";
+
+        $mailbox = new Fixtures\Mailbox('', '', '');
+
+        $this->assertSame(
+            '<first@example.com> <second@example.com>',
+            $mailbox->getMailHeaderFieldValueForTests($headersRaw, 'References')
+        );
+    }
+
+    public function testGetThreadingHeadersFallsBackToRawHeadersWhenParsedMessageIdIsMissing(): void
+    {
+        $headersRaw =
+            "Message-ID: <ticket-123@example.com>\r\n".
+            "In-Reply-To: <parent-456@example.com>\r\n".
+            "References: <root@example.com>\r\n".
+            "\t<parent-456@example.com>\r\n";
+
+        $head = new stdClass();
+
+        $mailbox = new Fixtures\Mailbox('', '', '');
+
+        $this->assertSame(
+            [
+                'messageId' => '<ticket-123@example.com>',
+                'inReplyTo' => '<parent-456@example.com>',
+                'references' => '<root@example.com> <parent-456@example.com>',
+            ],
+            $mailbox->getThreadingHeadersForTests($head, $headersRaw)
+        );
+    }
+
+    public function testGetThreadingHeadersPrefersParsedMessageIdWhenAvailable(): void
+    {
+        $headersRaw = "Message-ID: <raw@example.com>\r\n";
+
+        $head = new stdClass();
+        $head->message_id = '<parsed@example.com>';
+
+        $mailbox = new Fixtures\Mailbox('', '', '');
+
+        $this->assertSame(
+            [
+                'messageId' => '<parsed@example.com>',
+                'inReplyTo' => null,
+                'references' => null,
+            ],
+            $mailbox->getThreadingHeadersForTests($head, $headersRaw)
+        );
+    }
+}