Merge pull request #154 from DirectoryTree/feature-153

Add ability to lazy load message contents (html, text, and attachments)

Author: stevebauman

src/HasParsedMessage.php

@@ -21,7 +21,7 @@ trait HasParsedMessage
     /**
      * The parsed message.
      */
-    protected ?IMessage $parsed = null;
+    protected ?IMessage $message = null;
 
     /**
      * Get the message date and time.
@@ -243,7 +243,7 @@ public function parse(): IMessage
             throw new RuntimeException('Cannot parse an empty message');
         }
 
-        return $this->parsed ??= MessageParser::parse((string) $this);
+        return $this->message ??= MessageParser::parse((string) $this);
     }
 
     /**

src/Message.php

@@ -12,7 +12,11 @@
 
 class Message implements Arrayable, JsonSerializable, MessageInterface
 {
-    use HasFlags, HasParsedMessage;
+    use HasFlags, HasParsedMessage {
+        text as protected getParsedText;
+        html as protected getParsedHtml;
+        attachments as protected getParsedAttachments;
+    }
 
     /**
      * The parsed body structure.
@@ -108,12 +112,16 @@ public function hasBody(): bool
     /**
      * Get the message's body structure.
      */
-    public function bodyStructure(): ?BodyStructureCollection
+    public function bodyStructure(bool $lazy = false): ?BodyStructureCollection
     {
         if ($this->bodyStructure) {
             return $this->bodyStructure;
         }
 
+        if (! $this->bodyStructureData && $lazy) {
+            $this->bodyStructureData = $this->fetchBodyStructureData();
+        }
+
         if (! $tokens = $this->bodyStructureData?->tokens()) {
             return null;
         }
@@ -218,6 +226,67 @@ public function move(string $folder, bool $expunge = false): ?int
         }
     }
 
+    /**
+     * Get the message's text content.
+     */
+    public function text(bool $lazy = false): ?string
+    {
+        if ($lazy && ! $this->hasBody()) {
+            if ($part = $this->bodyStructure(lazy: true)?->text()) {
+                return Support\BodyPartDecoder::text($part, $this->bodyPart($part->partNumber()));
+            }
+        }
+
+        return $this->getParsedText();
+    }
+
+    /**
+     * Get the message's HTML content.
+     */
+    public function html(bool $lazy = false): ?string
+    {
+        if ($lazy && ! $this->hasBody()) {
+            if ($part = $this->bodyStructure(lazy: true)?->html()) {
+                return Support\BodyPartDecoder::text($part, $this->bodyPart($part->partNumber()));
+            }
+        }
+
+        return $this->getParsedHtml();
+    }
+
+    /**
+     * Get the message's attachments.
+     *
+     * @return Attachment[]
+     */
+    public function attachments(bool $lazy = false): array
+    {
+        if ($lazy && ! $this->hasBody()) {
+            return $this->getLazyAttachments();
+        }
+
+        return $this->getParsedAttachments();
+    }
+
+    /**
+     * Get attachments using lazy loading from body structure.
+     *
+     * @return Attachment[]
+     */
+    protected function getLazyAttachments(): array
+    {
+        return array_map(
+            fn (BodyStructurePart $part) => new Attachment(
+                $part->filename(),
+                $part->id(),
+                $part->contentType(),
+                $part->disposition()?->type()?->value,
+                new Support\LazyBodyPartStream($this, $part),
+            ),
+            $this->bodyStructure(lazy: true)?->attachments() ?? []
+        );
+    }
+
     /**
      * Fetch a specific body part by part number.
      */
@@ -296,4 +365,27 @@ public function isEmpty(): bool
     {
         return ! $this->hasHead() && ! $this->hasBody();
     }
+
+    /**
+     * Fetch the body structure data from the server.
+     */
+    protected function fetchBodyStructureData(): ?ListData
+    {
+        $response = $this->folder
+            ->mailbox()
+            ->connection()
+            ->bodyStructure($this->uid);
+
+        if ($response->isEmpty()) {
+            return null;
+        }
+
+        $data = $response->first()->tokenAt(3);
+
+        if (! $data instanceof ListData) {
+            return null;
+        }
+
+        return $data->lookup('BODYSTRUCTURE');
+    }
 }

src/MessageQuery.php

@@ -21,7 +21,7 @@
 use Illuminate\Support\ItemNotFoundException;
 
 /**
- * @mixin \DirectoryTree\ImapEngine\Connection\ImapQueryBuilder
+ * @mixin ImapQueryBuilder
  */
 class MessageQuery implements MessageQueryInterface
 {

src/MessageQueryInterface.php

@@ -4,12 +4,13 @@
 
 use BackedEnum;
 use DirectoryTree\ImapEngine\Collections\MessageCollection;
+use DirectoryTree\ImapEngine\Connection\ImapQueryBuilder;
 use DirectoryTree\ImapEngine\Enums\ImapFetchIdentifier;
 use DirectoryTree\ImapEngine\Enums\ImapSortKey;
 use DirectoryTree\ImapEngine\Pagination\LengthAwarePaginator;
 
 /**
- * @mixin \DirectoryTree\ImapEngine\Connection\ImapQueryBuilder
+ * @mixin ImapQueryBuilder
  */
 interface MessageQueryInterface
 {

src/Support/BodyPartDecoder.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Support;
+
+use DirectoryTree\ImapEngine\BodyStructurePart;
+use DirectoryTree\ImapEngine\MessageParser;
+
+class BodyPartDecoder
+{
+    /**
+     * Decode raw text/html content using the part's metadata.
+     */
+    public static function text(BodyStructurePart $part, ?string $content): ?string
+    {
+        $content = rtrim($content ?? '', "\r\n");
+
+        if ($content === '') {
+            return null;
+        }
+
+        $parsed = MessageParser::parse(
+            MimeMessage::make($part, $content)
+        );
+
+        return $part->subtype() === 'html'
+            ? $parsed->getHtmlContent()
+            : $parsed->getTextContent();
+    }
+
+    /**
+     * Decode raw binary content using the part's metadata.
+     */
+    public static function binary(BodyStructurePart $part, ?string $content): ?string
+    {
+        $content = rtrim($content ?? '', "\r\n");
+
+        if ($content === '') {
+            return null;
+        }
+
+        $parsed = MessageParser::parse(
+            MimeMessage::make($part, $content)
+        );
+
+        return $parsed->getBinaryContentStream()?->getContents();
+    }
+}