Update all exceptions to be named appropriately

stevebauman · stevebauman · commit 466405e85a23 · 2025-02-12T23:15:21.000-05:00
diff --git a/src/Connection/ImapConnection.php b/src/Connection/ImapConnection.php
@@ -12,14 +12,18 @@
 use DirectoryTree\ImapEngine\Connection\Streams\StreamInterface;
 use DirectoryTree\ImapEngine\Connection\Tokens\Token;
 use DirectoryTree\ImapEngine\Enums\ImapFetchIdentifier;
-use DirectoryTree\ImapEngine\Exceptions\CommandFailedException;
-use DirectoryTree\ImapEngine\Exceptions\ConnectionClosedException;
-use DirectoryTree\ImapEngine\Exceptions\ConnectionFailedException;
-use DirectoryTree\ImapEngine\Exceptions\ConnectionTimedOutException;
+use DirectoryTree\ImapEngine\Exceptions\ImapCommandException;
+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionClosedException;
+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionException;
+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionFailedException;
+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionTimedOutException;
 use DirectoryTree\ImapEngine\Exceptions\Exception;
+use DirectoryTree\ImapEngine\Exceptions\ImapResponseException;
+use DirectoryTree\ImapEngine\Exceptions\ImapStreamException;
 use DirectoryTree\ImapEngine\Exceptions\RuntimeException;
 use DirectoryTree\ImapEngine\Support\Str;
 use Generator;
+use LogicException;
 
 class ImapConnection implements ConnectionInterface
 {
@@ -88,7 +92,7 @@ public function connect(string $host, ?int $port = null, array $options = []): v
         $this->assertNextResponse(
             fn (Response $response) => $response instanceof UntaggedResponse,
             fn (UntaggedResponse $response) => $response->type()->is('OK'),
-            fn () => new ConnectionFailedException("Connection to $host:$port failed")
+            fn () => new ImapConnectionFailedException("Connection to $host:$port failed")
         );
 
         if ($transport === 'starttls') {
@@ -150,7 +154,7 @@ public function login(string $user, string $password): TaggedResponse
         $this->send('LOGIN', Str::literal([$user, $password]), $tag);
 
         return $this->assertTaggedResponse($tag, fn (TaggedResponse $response) => (
-            CommandFailedException::make($this->result->command()->redacted(), $response)
+            ImapCommandException::make($this->result->command()->redacted(), $response)
         ));
     }
 
@@ -177,7 +181,7 @@ public function authenticate(string $user, string $token): TaggedResponse
         $this->send('AUTHENTICATE', ['XOAUTH2', Str::credentials($user, $token)], $tag);
 
         return $this->assertTaggedResponse($tag, fn (TaggedResponse $response) => (
-            CommandFailedException::make($this->result->command()->redacted(), $response)
+            ImapCommandException::make($this->result->command()->redacted(), $response)
         ));
     }
 
@@ -190,11 +194,7 @@ public function startTls(): void
 
         $this->assertTaggedResponse($tag);
 
-        $this->stream->setSocketSetCrypto(true, match (true) {
-            defined('STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT') => STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT,
-            defined('STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT') => STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT,
-            default => STREAM_CRYPTO_METHOD_TLS_CLIENT,
-        });
+        $this->stream->setSocketSetCrypto(true, STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT);
     }
 
     /**
@@ -522,7 +522,7 @@ public function idle(int $timeout): Generator
         $this->assertNextResponse(
             fn (Response $response) => $response instanceof ContinuationResponse,
             fn (ContinuationResponse $response) => true,
-            fn (ContinuationResponse $response) => CommandFailedException::make(new ImapCommand('', 'IDLE'), $response),
+            fn (ContinuationResponse $response) => ImapCommandException::make(new ImapCommand('', 'IDLE'), $response),
         );
 
         while ($response = $this->nextReply()) {
@@ -543,7 +543,7 @@ public function done(): void
         $this->assertNextResponse(
             fn (Response $response) => $response instanceof TaggedResponse,
             fn (TaggedResponse $response) => $response->successful(),
-            fn (TaggedResponse $response) => CommandFailedException::make(new ImapCommand('', 'DONE'), $response),
+            fn (TaggedResponse $response) => ImapCommandException::make(new ImapCommand('', 'DONE'), $response),
         );
     }
 
@@ -575,7 +575,7 @@ public function send(string $name, array $tokens = [], ?string &$tag = null): vo
     protected function write(string $data): void
     {
         if ($this->stream->fwrite($data."\r\n") === false) {
-            throw new RuntimeException('Failed to write data to stream');
+            throw new ImapStreamException('Failed to write data to stream');
         }
 
         $this->logger?->sent($data);
@@ -658,7 +658,7 @@ protected function assertTaggedResponse(string $tag, ?callable $exception = null
                 $response->successful()
             ),
             $exception ?? fn (TaggedResponse $response) => (
-                CommandFailedException::make($this->result->command(), $response)
+                ImapCommandException::make($this->result->command(), $response)
             ),
         );
     }
@@ -681,7 +681,7 @@ protected function assertNextResponse(callable $filter, callable $assertion, cal
             throw $exception($response);
         }
 
-        throw new RuntimeException('No matching response found');
+        throw new ImapResponseException('No matching response found');
     }
 
     /**
@@ -695,7 +695,7 @@ protected function assertNextResponse(callable $filter, callable $assertion, cal
     protected function nextResponse(callable $filter): Response
     {
         if (! $this->parser) {
-            throw new RuntimeException('No parser instance set');
+            throw new LogicException('No parser instance set');
         }
 
         while ($response = $this->nextReply()) {
@@ -710,7 +710,7 @@ protected function nextResponse(callable $filter): Response
             }
         }
 
-        throw new RuntimeException('No matching response found');
+        throw new ImapResponseException('No matching response found');
     }
 
     /**
@@ -722,9 +722,9 @@ protected function nextReply(): Data|Token|Response|null
             $meta = $this->stream->meta();
 
             throw match (true) {
-                $meta['timed_out'] ?? false => new ConnectionTimedOutException('Stream timed out, no response'),
-                $meta['eof'] ?? false => new ConnectionClosedException('Server closed the connection (EOF)'),
-                default => new RuntimeException('Unknown read error, no response: '.json_encode($meta)),
+                $meta['timed_out'] ?? false => new ImapConnectionTimedOutException('Stream timed out, no response'),
+                $meta['eof'] ?? false => new ImapConnectionClosedException('Server closed the connection (EOF)'),
+                default => new ImapConnectionException('Unknown stream error. Metadata: '.json_encode($meta)),
             };
         }
 
diff --git a/src/Connection/ImapParser.php b/src/Connection/ImapParser.php
@@ -16,7 +16,7 @@
 use DirectoryTree\ImapEngine\Connection\Tokens\ResponseCodeClose;
 use DirectoryTree\ImapEngine\Connection\Tokens\ResponseCodeOpen;
 use DirectoryTree\ImapEngine\Connection\Tokens\Token;
-use DirectoryTree\ImapEngine\Exceptions\ImapParseException;
+use DirectoryTree\ImapEngine\Exceptions\ImapParserException;
 
 class ImapParser
 {
@@ -55,7 +55,7 @@ public function next(): Data|Token|Response|null
         }
 
         if (! $this->currentToken) {
-            throw new ImapParseException('Empty response');
+            throw new ImapParserException('Empty response');
         }
 
         // If the token indicates the beginning of a list, parse it.
@@ -105,7 +105,7 @@ protected function parseUntaggedResponse(): UntaggedResponse
         if ($this->currentToken && $this->isEndOfResponseToken($this->currentToken)) {
             $this->currentToken = null;
         } else {
-            throw new ImapParseException('Unterminated untagged response');
+            throw new ImapParserException('Unterminated untagged response');
         }
 
         return new UntaggedResponse($elements);
@@ -134,7 +134,7 @@ protected function parseContinuationResponse(): ContinuationResponse
         if ($this->currentToken && $this->isEndOfResponseToken($this->currentToken)) {
             $this->currentToken = null;
         } else {
-            throw new ImapParseException('Unterminated continuation response');
+            throw new ImapParserException('Unterminated continuation response');
         }
 
         return new ContinuationResponse($elements);
@@ -161,7 +161,7 @@ protected function parseTaggedResponse(): TaggedResponse
         if ($this->currentToken && $this->isEndOfResponseToken($this->currentToken)) {
             $this->currentToken = null;
         } else {
-            throw new ImapParseException('Unterminated tagged response');
+            throw new ImapParserException('Unterminated tagged response');
         }
 
         return new TaggedResponse($tokens);
@@ -186,7 +186,7 @@ protected function parseBracketGroup(): ResponseCodeData
         }
 
         if ($this->currentToken === null) {
-            throw new ImapParseException('Unterminated bracket group in response');
+            throw new ImapParserException('Unterminated bracket group in response');
         }
 
         // Consume the closing ']' token.
@@ -200,7 +200,7 @@ protected function parseBracketGroup(): ResponseCodeData
      *
      * Lists are handled recursively: a list may contain nested lists.
      *
-     * @throws ImapParseException if the list is unterminated.
+     * @throws ImapParserException if the list is unterminated.
      */
     protected function parseList(): ListData
     {
@@ -220,7 +220,7 @@ protected function parseList(): ListData
 
         // If we reached the end without finding a closing ')', throw an exception.
         if ($this->currentToken === null) {
-            throw new ImapParseException('Unterminated list in response');
+            throw new ImapParserException('Unterminated list in response');
         }
 
         // Consume the closing ')' token.
diff --git a/src/Connection/ImapTokenizer.php b/src/Connection/ImapTokenizer.php
@@ -13,7 +13,7 @@
 use DirectoryTree\ImapEngine\Connection\Tokens\ResponseCodeClose;
 use DirectoryTree\ImapEngine\Connection\Tokens\ResponseCodeOpen;
 use DirectoryTree\ImapEngine\Connection\Tokens\Token;
-use DirectoryTree\ImapEngine\Exceptions\ImapParseException;
+use DirectoryTree\ImapEngine\Exceptions\ImapParserException;
 use DirectoryTree\ImapEngine\Exceptions\ImapStreamException;
 
 class ImapTokenizer
@@ -73,7 +73,7 @@ public function nextToken(): ?Token
             $this->ensureBuffer(1);
 
             if ($this->currentChar() !== "\n") {
-                throw new ImapParseException('Expected LF after CR');
+                throw new ImapParserException('Expected LF after CR');
             }
 
             $this->advance(); // Consume LF (\n)
@@ -177,7 +177,7 @@ protected function readQuotedString(): QuotedString
             $char = $this->currentChar();
 
             if ($char === null) {
-                throw new ImapParseException(sprintf(
+                throw new ImapParserException(sprintf(
                     'Unterminated quoted string at buffer offset %d. Buffer: "%s"',
                     $this->position,
                     substr($this->buffer, max(0, $this->position - 10), 20)
@@ -192,7 +192,7 @@ protected function readQuotedString(): QuotedString
                 $escapedChar = $this->currentChar();
 
                 if ($escapedChar === null) {
-                    throw new ImapParseException('Unterminated escape sequence in quoted string');
+                    throw new ImapParserException('Unterminated escape sequence in quoted string');
                 }
 
                 $value .= $escapedChar;
@@ -236,7 +236,7 @@ protected function readLiteral(): Literal
             $char = $this->currentChar();
 
             if ($char === null) {
-                throw new ImapParseException('Unterminated literal specifier');
+                throw new ImapParserException('Unterminated literal specifier');
             }
 
             if ($char === '}') {
@@ -257,7 +257,7 @@ protected function readLiteral(): Literal
         $crlf = substr($this->buffer, $this->position, 2);
 
         if ($crlf !== "\r\n") {
-            throw new ImapParseException('Expected CRLF after literal specifier');
+            throw new ImapParserException('Expected CRLF after literal specifier');
         }
 
         // Skip the CRLF.
@@ -296,7 +296,7 @@ protected function readLiteral(): Literal
 
         // Verify that the literal length matches the expected length.
         if (strlen($literal) !== $length) {
-            throw new ImapParseException(sprintf(
+            throw new ImapParserException(sprintf(
                 'Literal length mismatch: expected %d, got %d',
                 $length,
                 strlen($literal)
@@ -353,7 +353,7 @@ protected function readEmailAddress(): ?EmailAddress
             $char = $this->currentChar();
 
             if ($char === null) {
-                throw new ImapParseException('Unterminated email address, expected ">"');
+                throw new ImapParserException('Unterminated email address, expected ">"');
             }
 
             if ($char === '>') {
diff --git a/src/Connection/Streams/ImapStream.php b/src/Connection/Streams/ImapStream.php
@@ -2,7 +2,7 @@
 
 namespace DirectoryTree\ImapEngine\Connection\Streams;
 
-use DirectoryTree\ImapEngine\Exceptions\ConnectionFailedException;
+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionFailedException;
 
 class ImapStream implements StreamInterface
 {
@@ -28,7 +28,7 @@ public function open(string $transport, string $host, int $port, int $timeout, a
         );
 
         if (! $this->stream) {
-            throw new ConnectionFailedException('Stream failed to open: '.$errstr, $errno);
+            throw new ImapConnectionFailedException('Stream failed to open: '.$errstr, $errno);
         }
 
         return true;
diff --git a/src/Exceptions/ConnectionTimedOutException.php b/src/Exceptions/ConnectionTimedOutException.php
diff --git a/src/Exceptions/ImapCapabilityException.php b/src/Exceptions/ImapCapabilityException.php
@@ -2,4 +2,4 @@
 
 namespace DirectoryTree\ImapEngine\Exceptions;
 
-class ConnectionClosedException extends Exception {}
+class ImapCapabilityException extends Exception {}
diff --git a/src/Exceptions/ImapCommandException.php b/src/Exceptions/ImapCommandException.php
@@ -5,7 +5,7 @@
 use DirectoryTree\ImapEngine\Connection\ImapCommand;
 use DirectoryTree\ImapEngine\Connection\Responses\Response;
 
-class CommandFailedException extends Exception
+class ImapCommandException extends Exception
 {
     /**
      * Make a new instance from a failed command and response.
diff --git a/src/Exceptions/ImapConnectionClosedException.php b/src/Exceptions/ImapConnectionClosedException.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Exceptions;
+
+class ImapConnectionClosedException extends Exception {}
diff --git a/src/Exceptions/ImapConnectionException.php b/src/Exceptions/ImapConnectionException.php
@@ -2,4 +2,4 @@
 
 namespace DirectoryTree\ImapEngine\Exceptions;
 
-class ConnectionFailedException extends Exception {}
+class ImapConnectionException extends Exception {}
diff --git a/src/Exceptions/ImapConnectionFailedException.php b/src/Exceptions/ImapConnectionFailedException.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Exceptions;
+
+class ImapConnectionFailedException extends Exception {}
diff --git a/src/Exceptions/ImapConnectionTimedOutException.php b/src/Exceptions/ImapConnectionTimedOutException.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Exceptions;
+
+class ImapConnectionTimedOutException extends Exception {}
diff --git a/src/Exceptions/ImapParserException.php b/src/Exceptions/ImapParserException.php
@@ -2,4 +2,4 @@
 
 namespace DirectoryTree\ImapEngine\Exceptions;
 
-class ImapParseException extends Exception {}
+class ImapParserException extends Exception {}
diff --git a/src/Exceptions/ImapResponseException.php b/src/Exceptions/ImapResponseException.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace DirectoryTree\ImapEngine\Exceptions;
+
+class ImapResponseException extends Exception {}
diff --git a/src/Exceptions/ImapStreamException.php b/src/Exceptions/ImapStreamException.php
@@ -2,6 +2,4 @@
 
 namespace DirectoryTree\ImapEngine\Exceptions;
 
-use Exception;
-
 class ImapStreamException extends Exception {}
diff --git a/src/Folder.php b/src/Folder.php
@@ -6,6 +6,7 @@
 use DirectoryTree\ImapEngine\Connection\Responses\UntaggedResponse;
 use DirectoryTree\ImapEngine\Enums\ImapFetchIdentifier;
 use DirectoryTree\ImapEngine\Exceptions\Exception;
+use DirectoryTree\ImapEngine\Exceptions\ImapCapabilityException;
 use DirectoryTree\ImapEngine\Exceptions\RuntimeException;
 
 class Folder
@@ -91,7 +92,7 @@ public function messages(): MessageQuery
     public function idle(callable $callback, callable $query, int $timeout = 300): void
     {
         if (! $this->hasCapability('IDLE')) {
-            throw new RuntimeException('IMAP server does not support IDLE');
+            throw new ImapCapabilityException('IMAP server does not support IDLE');
         }
 
         // The message query to use when fetching messages.
diff --git a/src/Idle.php b/src/Idle.php
diff --git a/tests/Unit/Connection/ImapConnectionTest.php b/tests/Unit/Connection/ImapConnectionTest.php
diff --git a/tests/Unit/Connection/ImapTokenizerTest.php b/tests/Unit/Connection/ImapTokenizerTest.php
diff --git a/tests/Unit/MailboxTest.php b/tests/Unit/MailboxTest.php

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@`
`16`	`16`	`use DirectoryTree\ImapEngine\Connection\Tokens\ResponseCodeClose;`
`17`	`17`	`use DirectoryTree\ImapEngine\Connection\Tokens\ResponseCodeOpen;`
`18`	`18`	`use DirectoryTree\ImapEngine\Connection\Tokens\Token;`
`19`		`-use DirectoryTree\ImapEngine\Exceptions\ImapParseException;`
	`19`	`+use DirectoryTree\ImapEngine\Exceptions\ImapParserException;`
`20`	`20`
`21`	`21`	`class ImapParser`
`22`	`22`	`{`
`@@ -55,7 +55,7 @@ public function next(): Data\|Token\|Response\|null`
`55`	`55`	`}`
`56`	`56`
`57`	`57`	`if (! $this->currentToken) {`
`58`		`- throw new ImapParseException('Empty response');`
	`58`	`+ throw new ImapParserException('Empty response');`
`59`	`59`	`}`
`60`	`60`
`61`	`61`	`// If the token indicates the beginning of a list, parse it.`
`@@ -105,7 +105,7 @@ protected function parseUntaggedResponse(): UntaggedResponse`
`105`	`105`	`if ($this->currentToken && $this->isEndOfResponseToken($this->currentToken)) {`
`106`	`106`	`$this->currentToken = null;`
`107`	`107`	`} else {`
`108`		`- throw new ImapParseException('Unterminated untagged response');`
	`108`	`+ throw new ImapParserException('Unterminated untagged response');`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`return new UntaggedResponse($elements);`
`@@ -134,7 +134,7 @@ protected function parseContinuationResponse(): ContinuationResponse`
`134`	`134`	`if ($this->currentToken && $this->isEndOfResponseToken($this->currentToken)) {`
`135`	`135`	`$this->currentToken = null;`
`136`	`136`	`} else {`
`137`		`- throw new ImapParseException('Unterminated continuation response');`
	`137`	`+ throw new ImapParserException('Unterminated continuation response');`
`138`	`138`	`}`
`139`	`139`
`140`	`140`	`return new ContinuationResponse($elements);`
`@@ -161,7 +161,7 @@ protected function parseTaggedResponse(): TaggedResponse`
`161`	`161`	`if ($this->currentToken && $this->isEndOfResponseToken($this->currentToken)) {`
`162`	`162`	`$this->currentToken = null;`
`163`	`163`	`} else {`
`164`		`- throw new ImapParseException('Unterminated tagged response');`
	`164`	`+ throw new ImapParserException('Unterminated tagged response');`
`165`	`165`	`}`
`166`	`166`
`167`	`167`	`return new TaggedResponse($tokens);`
`@@ -186,7 +186,7 @@ protected function parseBracketGroup(): ResponseCodeData`
`186`	`186`	`}`
`187`	`187`
`188`	`188`	`if ($this->currentToken === null) {`
`189`		`- throw new ImapParseException('Unterminated bracket group in response');`
	`189`	`+ throw new ImapParserException('Unterminated bracket group in response');`
`190`	`190`	`}`
`191`	`191`
`192`	`192`	`// Consume the closing ']' token.`
`@@ -200,7 +200,7 @@ protected function parseBracketGroup(): ResponseCodeData`
`200`	`200`	`*`
`201`	`201`	`* Lists are handled recursively: a list may contain nested lists.`
`202`	`202`	`*`
`203`		`- * @throws ImapParseException if the list is unterminated.`
	`203`	`+ * @throws ImapParserException if the list is unterminated.`
`204`	`204`	`*/`
`205`	`205`	`protected function parseList(): ListData`
`206`	`206`	`{`
`@@ -220,7 +220,7 @@ protected function parseList(): ListData`
`220`	`220`
`221`	`221`	`// If we reached the end without finding a closing ')', throw an exception.`
`222`	`222`	`if ($this->currentToken === null) {`
`223`		`- throw new ImapParseException('Unterminated list in response');`
	`223`	`+ throw new ImapParserException('Unterminated list in response');`
`224`	`224`	`}`
`225`	`225`
`226`	`226`	`// Consume the closing ')' token.`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`
`3`	`3`	`namespace DirectoryTree\ImapEngine\Connection\Streams;`
`4`	`4`
`5`		`-use DirectoryTree\ImapEngine\Exceptions\ConnectionFailedException;`
	`5`	`+use DirectoryTree\ImapEngine\Exceptions\ImapConnectionFailedException;`
`6`	`6`
`7`	`7`	`class ImapStream implements StreamInterface`
`8`	`8`	`{`
`@@ -28,7 +28,7 @@ public function open(string $transport, string $host, int $port, int $timeout, a`
`28`	`28`	`);`
`29`	`29`
`30`	`30`	`if (! $this->stream) {`
`31`		`- throw new ConnectionFailedException('Stream failed to open: '.$errstr, $errno);`
	`31`	`+ throw new ImapConnectionFailedException('Stream failed to open: '.$errstr, $errno);`
`32`	`32`	`}`
`33`	`33`
`34`	`34`	`return true;`
Original file line number	Diff line number	Diff line change
`@@ -2,4 +2,4 @@`
`2`	`2`
`3`	`3`	`namespace DirectoryTree\ImapEngine\Exceptions;`
`4`	`4`
`5`		`-class ConnectionClosedException extends Exception {}`
	`5`	`+class ImapCapabilityException extends Exception {}`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`use DirectoryTree\ImapEngine\Connection\ImapCommand;`
`6`	`6`	`use DirectoryTree\ImapEngine\Connection\Responses\Response;`
`7`	`7`
`8`		`-class CommandFailedException extends Exception`
	`8`	`+class ImapCommandException extends Exception`
`9`	`9`	`{`
`10`	`10`	`/**`
`11`	`11`	`* Make a new instance from a failed command and response.`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +<?php
++
 +namespace DirectoryTree\ImapEngine\Exceptions;
++
 +class ImapConnectionClosedException extends Exception {}
Original file line number	Diff line number	Diff line change
`@@ -2,4 +2,4 @@`
`2`	`2`
`3`	`3`	`namespace DirectoryTree\ImapEngine\Exceptions;`
`4`	`4`
`5`		`-class ConnectionFailedException extends Exception {}`
	`5`	`+class ImapConnectionException extends Exception {}`