Implement semantic exception hierarchy with proper inheritance patterns

Author: Mohamed Khaled

src/Providers/Http/Exception/ClientException.php

@@ -4,7 +4,11 @@
 
 namespace WordPress\AiClient\Providers\Http\Exception;
 
+use Psr\Http\Message\RequestInterface;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Providers\Http\DTO\Request;
 use WordPress\AiClient\Providers\Http\DTO\Response;
+use WordPress\AiClient\Providers\Http\Utilities\ErrorMessageExtractor;
 
 /**
  * Exception thrown for 4xx HTTP client errors.
@@ -14,8 +18,35 @@
  *
  * @since n.e.x.t
  */
-class ClientException extends RequestException
+class ClientException extends InvalidArgumentException
 {
+    /**
+     * The request that failed.
+     *
+     * @var Request|null
+     */
+    protected ?Request $request = null;
+
+    /**
+     * Returns the request that failed as our Request DTO.
+     *
+     * @since n.e.x.t
+     *
+     * @return Request
+     * @throws \RuntimeException If no request is available
+     */
+    public function getRequest(): Request
+    {
+        if ($this->request === null) {
+            throw new \RuntimeException(
+                'Request object not available. This exception was directly instantiated. ' .
+                'Use a factory method that provides request context.'
+            );
+        }
+
+        return $this->request;
+    }
+
     /**
      * Creates a ClientException from a 400 Bad Request response.
      *
@@ -30,6 +61,43 @@ public static function fromBadRequestResponse(string $errorDetail = 'Invalid req
         return new self($message, 400);
     }
 
+    /**
+     * Creates a ClientException from a bad request.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestInterface $psrRequest The PSR-7 request that failed.
+     * @param string $errorDetail Details about what made the request bad.
+     * @return self
+     */
+    public static function fromBadRequest(
+        RequestInterface $psrRequest,
+        string $errorDetail = 'Invalid request parameters'
+    ): self {
+        $request = Request::fromPsrRequest($psrRequest);
+        $message = sprintf('Bad request to %s (400): %s', $request->getUri(), $errorDetail);
+
+        $exception = new self($message, 400);
+        $exception->request = $request;
+        return $exception;
+    }
+
+    /**
+     * Creates a ClientException from a bad request to a specific URI.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $uri The URI that was requested.
+     * @param string $errorDetail Details about what made the request bad.
+     * @return self
+     *
+     * @deprecated Use fromBadRequest() with RequestInterface for better type safety
+     */
+    public static function fromBadRequestToUri(string $uri, string $errorDetail = 'Invalid request parameters'): self
+    {
+        return new self(sprintf('Bad request to %s (400): %s', $uri, $errorDetail), 400);
+    }
+
     /**
      * Creates a ClientException from a client error response (4xx).
      *
@@ -48,28 +116,10 @@ public static function fromClientError(Response $response): self
             $response->getStatusCode()
         );
 
-        // Handle common error formats in API responses
-        $data = $response->getData();
-        if (
-            is_array($data) &&
-            isset($data['error']) &&
-            is_array($data['error']) &&
-            isset($data['error']['message']) &&
-            is_string($data['error']['message'])
-        ) {
-            $errorMessage .= ' - ' . $data['error']['message'];
-        } elseif (
-            is_array($data) &&
-            isset($data['error']) &&
-            is_string($data['error'])
-        ) {
-            $errorMessage .= ' - ' . $data['error'];
-        } elseif (
-            is_array($data) &&
-            isset($data['message']) &&
-            is_string($data['message'])
-        ) {
-            $errorMessage .= ' - ' . $data['message'];
+        // Extract error message from response data using centralized utility
+        $extractedError = ErrorMessageExtractor::extractFromResponseData($response->getData());
+        if ($extractedError !== null) {
+            $errorMessage .= ' - ' . $extractedError;
         }
 
         return new self($errorMessage, $response->getStatusCode());

src/Providers/Http/Exception/NetworkException.php

@@ -4,8 +4,9 @@
 
 namespace WordPress\AiClient\Providers\Http\Exception;
 
-use Psr\Http\Client\NetworkExceptionInterface;
 use Psr\Http\Message\RequestInterface;
+use WordPress\AiClient\Common\Exception\RuntimeException;
+use WordPress\AiClient\Providers\Http\DTO\Request;
 
 /**
  * Exception thrown for network-related errors.
@@ -15,54 +16,55 @@
  *
  * @since n.e.x.t
  */
-class NetworkException extends RequestException implements NetworkExceptionInterface
+class NetworkException extends RuntimeException
 {
     /**
      * The request that failed.
      *
-     * @var RequestInterface|null
+     * @var Request|null
      */
-    private ?RequestInterface $request = null;
+    protected ?Request $request = null;
+
+    /**
+     * Returns the request that failed as our Request DTO.
+     *
+     * @since n.e.x.t
+     *
+     * @return Request
+     * @throws \RuntimeException If no request is available
+     */
+    public function getRequest(): Request
+    {
+        if ($this->request === null) {
+            throw new \RuntimeException(
+                'Request object not available. This exception was directly instantiated. ' .
+                'Use a factory method that provides request context.'
+            );
+        }
+
+        return $this->request;
+    }
 
     /**
      * Creates a NetworkException from a PSR-18 network exception.
      *
      * @since n.e.x.t
      *
-     * @param RequestInterface $request The request that failed.
+     * @param RequestInterface $psrRequest The PSR-7 request that failed.
      * @param \Throwable $networkException The PSR-18 network exception.
      * @return self
      */
-    public static function fromPsr18NetworkException(RequestInterface $request, \Throwable $networkException): self
+    public static function fromPsr18NetworkException(RequestInterface $psrRequest, \Throwable $networkException): self
     {
+        $request = Request::fromPsrRequest($psrRequest);
         $message = sprintf(
             'Network error occurred while sending request to %s: %s',
-            (string) $request->getUri(),
+            $request->getUri(),
             $networkException->getMessage()
         );
 
         $exception = new self($message, 0, $networkException);
         $exception->request = $request;
         return $exception;
     }
-
-    /**
-     * Returns the request that failed.
-     *
-     * @since n.e.x.t
-     *
-     * @return RequestInterface
-     * @throws \RuntimeException If no request is available (when directly instantiated)
-     */
-    public function getRequest(): RequestInterface
-    {
-        if ($this->request === null) {
-            throw new \RuntimeException(
-                'Request object not available. This exception was directly instantiated. ' .
-                'Use fromPsr18NetworkException() factory method for PSR-18 compliance.'
-            );
-        }
-
-        return $this->request;
-    }
 }