Add support for fetch modifiers in ImapConnection

src/Connection/ConnectionInterface.php

@@ -181,7 +181,7 @@ public function flags(int|array $ids): ResponseCollection;
      *
      * @see https://datatracker.ietf.org/doc/html/rfc9051#name-fetch-command
      */
-    public function fetch(array|string $items, array|int $from, mixed $to = null, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid): ResponseCollection;
+    public function fetch(array|string $items, array|int $from, mixed $to = null, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid, array|string $modifiers = []): ResponseCollection;
 
     /**
      * Send a "RFC822.SIZE" command.

src/Connection/ImapConnection.php

@@ -630,13 +630,14 @@ protected function write(string $data): void
     /**
      * Fetch one or more items for one or more messages.
      */
-    public function fetch(array|string $items, array|int $from, mixed $to = null, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid): ResponseCollection
+    public function fetch(array|string $items, array|int $from, mixed $to = null, ImapFetchIdentifier $identifier = ImapFetchIdentifier::Uid, array|string $modifiers = []): ResponseCollection
     {
         $prefix = ($identifier === ImapFetchIdentifier::Uid) ? 'UID' : '';
 
         $this->send(trim($prefix.' FETCH'), [
             Str::set($from, $to),
             Str::list((array) $items),
+            Str::list((array) $modifiers),
         ], $tag);
 
         $this->assertTaggedResponse($tag);

src/Support/Str.php

@@ -13,12 +13,18 @@ public static function list(array $list): string
     {
         $values = [];
 
-        foreach ($list as $value) {
+        foreach ($list as $key => $value) {
             if (is_array($value)) {
-                $values[] = static::list($value);
+                $token = static::list($value);
             } else {
-                $values[] = $value;
+                $token = $value;
             }
+
+            if (is_string($key)) {
+                $token = $key.' '.$token;
+            }
+
+            $values[] = $token;
         }
 
         return sprintf('(%s)', implode(' ', $values));

tests/Unit/Support/StrTest.php

@@ -65,6 +65,11 @@
     expect(Str::list([]))->toBe('()');
 });
 
+test('list returns a properly formatted parenthesized list for an array with string keys', function () {
+    expect(Str::list(['a' => '"b"', 'c' => '"d"']))->toBe('(a "b" c "d")');
+    expect(Str::list(['a' => ['"b"', '"c"'], 'd' => '"e"']))->toBe('(a ("b" "c") d "e")');
+});
+
 test('enums returns value for a single backed enum', function () {
     $result = Str::enums(ImapFlag::Seen);