refactor: list command parsing

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-09-25 11:45:44 -04:00
parent 56fc949e83
commit cd724df8ec
2 changed files with 121 additions and 103 deletions
@@ -0,0 +1,116 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXM\ProviderImap\Client\Protocol\Parser;
+
+use KTXM\ProviderImap\Client\ImapException;
+use KTXM\ProviderImap\Client\Mailbox;
+
+/**
+ * Decodes an individual LIST response payload into a mailbox.
+ */
+final class ListResponseParser
+{
+    public function parse(string $payload): Mailbox
+    {
+        $payload = trim($payload);
+        $offset = 0;
+
+        $attributesToken = $this->readToken($payload, $offset);
+        $delimiterToken = $this->readToken($payload, $offset);
+        $nameToken = $this->readToken($payload, $offset);
+
+        if ($attributesToken === null || $delimiterToken === null || $nameToken === null) {
+            throw new ImapException('Unable to parse LIST response payload: ' . $payload);
+        }
+
+        $attributeString = trim($attributesToken, '() ');
+        $attributes = $attributeString === '' || strtoupper($attributeString) === 'NIL'
+            ? []
+            : array_map('strtoupper', preg_split('/\s+/', $attributeString) ?: []);
+
+        $delimiter = $this->decodeAtom($delimiterToken);
+        $name = $this->decodeMailboxName($nameToken);
+
+        return new Mailbox($name, $delimiter, $attributes);
+    }
+
+    private function readToken(string $payload, int &$offset): ?string
+    {
+        $length = strlen($payload);
+
+        while ($offset < $length && ctype_space($payload[$offset])) {
+            $offset++;
+        }
+
+        if ($offset >= $length) {
+            return null;
+        }
+
+        if ($payload[$offset] === '(') {
+            $end = strpos($payload, ')', $offset);
+
+            if ($end === false) {
+                throw new ImapException('Unterminated LIST attribute block: ' . $payload);
+            }
+
+            $token = substr($payload, $offset, $end - $offset + 1);
+            $offset = $end + 1;
+
+            return $token;
+        }
+
+        if ($payload[$offset] === '"') {
+            $start = $offset;
+            $offset++;
+
+            while ($offset < $length) {
+                if ($payload[$offset] === '\\') {
+                    $offset += 2;
+                    continue;
+                }
+
+                if ($payload[$offset] === '"') {
+                    $offset++;
+                    return substr($payload, $start, $offset - $start);
+                }
+
+                $offset++;
+            }
+
+            throw new ImapException('Unterminated quoted LIST token: ' . $payload);
+        }
+
+        $start = $offset;
+        while ($offset < $length && !ctype_space($payload[$offset])) {
+            $offset++;
+        }
+
+        return substr($payload, $start, $offset - $start);
+    }
+
+    private function decodeAtom(string $value): ?string
+    {
+        $value = trim($value);
+
+        if (strtoupper($value) === 'NIL') {
+            return null;
+        }
+
+        if (str_starts_with($value, '"') && str_ends_with($value, '"')) {
+            return stripcslashes(substr($value, 1, -1));
+        }
+
+        return $value;
+    }
+
+    private function decodeMailboxName(string $value): string
+    {
+        $name = $this->decodeAtom($value);
+
+        // LIST may advertise the root mailbox as an empty quoted string.
+        return $name ?? '';
+    }
+
+}