Add findOrFail messages method

Author: stevebauman

src/MessageQuery.php

@@ -3,6 +3,7 @@
 namespace DirectoryTree\ImapEngine;
 
 use DirectoryTree\ImapEngine\Collections\MessageCollection;
+use DirectoryTree\ImapEngine\Collections\ResponseCollection;
 use DirectoryTree\ImapEngine\Connection\ConnectionInterface;
 use DirectoryTree\ImapEngine\Connection\ImapQueryBuilder;
 use DirectoryTree\ImapEngine\Connection\Responses\UntaggedResponse;
@@ -525,24 +526,44 @@ public function paginate(int $perPage = 5, $page = null, string $pageName = 'pag
         return $this->get()->paginate($perPage, $this->page, $pageName, true);
     }
 
+    /**
+     * Find a message by the given identifier type or throw an exception.
+     */
+    public function findOrFail(int $id, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid)
+    {
+        $uid = $this->uid($id, $identifier)
+            ->firstOrFail() // Untagged response
+            ->tokenAt(3) // ListData
+            ->tokenAt(1) // Atom
+            ->value; // UID
+
+        return $this->process(new MessageCollection([$uid]))->firstOrFail();
+    }
+
     /**
      * Find a message by the given identifier type.
      */
-    public function find(int $id, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid): Message
+    public function find(int $id, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid): ?Message
     {
-        // If the sequence is not UID, we'll need to fetch the UID first.
-        $uid = match ($identifier) {
-            ImapFetchIdentifier::Uid => $id,
-            ImapFetchIdentifier::MessageNumber => $this->connection()->uid([$id]) // ResponseCollection
-                ->firstOrFail() // Untagged response
-                ->tokenAt(3) // ListData
-                ->tokenAt(1) // Atom
-                ->value // UID
-        };
+        if (! $response = $this->uid($id, $identifier)->first()) {
+            return null;
+        }
+
+        $uid = $response->tokenAt(3) // ListData
+            ->tokenAt(1) // Atom
+            ->value; // UID
 
         return $this->process(new MessageCollection([$uid]))->first();
     }
 
+    /**
+     * Get the UID for theb given identifier.
+     */
+    protected function uid(int $id, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid): ResponseCollection
+    {
+        return $this->connection()->uid([$id], $identifier);
+    }
+
     /**
      * Get the connection instance.
      */

tests/Integration/MessagesTest.php

@@ -5,6 +5,7 @@
 use DirectoryTree\ImapEngine\DraftMessage;
 use DirectoryTree\ImapEngine\Folder;
 use DirectoryTree\ImapEngine\Message;
+use Illuminate\Support\ItemNotFoundException;
 
 function folder(): Folder
 {
@@ -54,6 +55,38 @@ function folder(): Folder
     expect($folder->messages()->first()->uid())->toBe($uid);
 });
 
+test('find', function () {
+    $folder = folder();
+
+    $uid = $folder->messages()->append(
+        new DraftMessage(
+            from: '[email protected]',
+            text: 'hello world',
+        ),
+    );
+
+    $message = $folder->messages()->find($uid);
+
+    expect($message)->toBeInstanceOf(Message::class);
+});
+
+test('find or fail', function () {
+    $folder = folder();
+
+    $uid = $folder->messages()->append(
+        new DraftMessage(
+            from: '[email protected]',
+            text: 'hello world',
+        ),
+    );
+
+    expect($folder->messages()->findOrFail($uid))->toBeInstanceOf(Message::class);
+
+    expect(function () use ($folder) {
+        $folder->messages()->findOrFail(999);
+    })->toThrow(ItemNotFoundException::class);
+});
+
 test('append', function () {
     $folder = folder();