Implement PSR-18 exception interfaces for HTTP client compliance

Author: Mohamed Khaled

src/Providers/Http/Exception/NetworkException.php

@@ -4,6 +4,8 @@
 
 namespace WordPress\AiClient\Providers\Http\Exception;
 
+use Psr\Http\Client\NetworkExceptionInterface;
+use Psr\Http\Message\RequestInterface;
 use WordPress\AiClient\Common\Exception\RuntimeException;
 
 /**
@@ -14,25 +16,53 @@
  *
  * @since n.e.x.t
  */
-class NetworkException extends RuntimeException
+class NetworkException extends RuntimeException implements NetworkExceptionInterface
 {
+    /**
+     * The request that failed.
+     *
+     * @var RequestInterface|null
+     */
+    private ?RequestInterface $request = null;
+
     /**
      * Creates a NetworkException from a PSR-18 network exception.
      *
      * @since n.e.x.t
      *
-     * @param string $uri The URI that was being requested.
+     * @param RequestInterface $request The request that failed.
      * @param \Throwable $networkException The PSR-18 network exception.
      * @return self
      */
-    public static function fromPsr18NetworkException(string $uri, \Throwable $networkException): self
+    public static function fromPsr18NetworkException(RequestInterface $request, \Throwable $networkException): self
     {
         $message = sprintf(
             'Network error occurred while sending request to %s: %s',
-            $uri,
+            (string) $request->getUri(),
             $networkException->getMessage()
         );
 
-        return new self($message, 0, $networkException);
+        $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;
     }
 }

src/Providers/Http/Exception/RequestException.php

@@ -4,6 +4,8 @@
 
 namespace WordPress\AiClient\Providers\Http\Exception;
 
+use Psr\Http\Client\RequestExceptionInterface;
+use Psr\Http\Message\RequestInterface;
 use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 
 /**
@@ -15,8 +17,33 @@
  *
  * @since n.e.x.t
  */
-class RequestException extends InvalidArgumentException
+class RequestException extends InvalidArgumentException implements RequestExceptionInterface
 {
+    /**
+     * The request that failed.
+     *
+     * @var RequestInterface|null
+     */
+    private ?RequestInterface $request = null;
+
+    /**
+     * Creates a RequestException from a bad request.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestInterface $request The request that failed.
+     * @param string $errorDetail Details about what made the request bad.
+     * @return self
+     */
+    public static function fromBadRequest(RequestInterface $request, string $errorDetail = 'Invalid request parameters'): self
+    {
+        $message = sprintf('Bad request to %s (400): %s', (string) $request->getUri(), $errorDetail);
+        
+        $exception = new self($message);
+        $exception->request = $request;
+        return $exception;
+    }
+
     /**
      * Creates a RequestException from a bad request to a specific URI.
      *
@@ -25,9 +52,30 @@ class RequestException extends InvalidArgumentException
      * @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 PSR-18 compliance
      */
     public static function fromBadRequestToUri(string $uri, string $errorDetail = 'Invalid request parameters'): self
     {
         return new self(sprintf('Bad request to %s (400): %s', $uri, $errorDetail));
     }
+
+    /**
+     * Returns the request that failed.
+     *
+     * @since n.e.x.t
+     *
+     * @return RequestInterface
+     * @throws \RuntimeException If no request is available (when using deprecated fromBadRequestToUri)
+     */
+    public function getRequest(): RequestInterface
+    {
+        if ($this->request === null) {
+            throw new \RuntimeException(
+                'Request object not available. This exception was created using the deprecated fromBadRequestToUri() method. Use fromBadRequest() instead for PSR-18 compliance.'
+            );
+        }
+        
+        return $this->request;
+    }
 }

src/Providers/Http/Exception/ResponseException.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Http\Exception;
 
+use Psr\Http\Client\ClientExceptionInterface;
 use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\Http\DTO\Response;
 
@@ -16,7 +17,7 @@
  *
  * @since 0.1.0
  */
-class ResponseException extends RuntimeException
+class ResponseException extends RuntimeException implements ClientExceptionInterface
 {
     /**
      * Creates a ResponseException for missing expected data.

src/Providers/Http/HttpTransporter.php

@@ -75,7 +75,7 @@ public function send(Request $request): Response
         try {
             $psr7Response = $this->client->sendRequest($psr7Request);
         } catch (\Psr\Http\Client\NetworkExceptionInterface $e) {
-            throw NetworkException::fromPsr18NetworkException($request->getUri(), $e);
+            throw NetworkException::fromPsr18NetworkException($psr7Request, $e);
         } catch (\Psr\Http\Client\ClientExceptionInterface $e) {
             // Handle other PSR-18 client exceptions that are not network-related
             throw new RuntimeException(
@@ -93,7 +93,7 @@ public function send(Request $request): Response
         if ($psr7Response->getStatusCode() === 400) {
             $body = (string) $psr7Response->getBody();
             $errorDetail = $body ? substr($body, 0, 200) : 'Invalid request parameters';
-            throw RequestException::fromBadRequestToUri($request->getUri(), $errorDetail);
+            throw RequestException::fromBadRequest($psr7Request, $errorDetail);
         }
 
         return $this->convertFromPsr7Response($psr7Response);