Add Middleware/Interceptor System for Request/Response Transformation

src/Fetch/Concerns/PerformsHttpRequests.php

@@ -13,6 +13,7 @@
 use GuzzleHttp\Exception\RequestException as GuzzleRequestException;
 use GuzzleHttp\Psr7\Request as GuzzleRequest;
 use Matrix\Exceptions\AsyncException;
+use Psr\Http\Message\RequestInterface;
 use React\Promise\PromiseInterface;
 
 use function Matrix\Support\async;
@@ -187,14 +188,98 @@ public function sendRequest(
             $handler->logRequest($methodStr, $fullUri, $guzzleOptions);
         }
 
-        // Send the request (async or sync)
+        // Check if middleware is available and should be used
+        if (method_exists($handler, 'hasMiddleware') && $handler->hasMiddleware()) {
+            return $handler->executeWithMiddleware($methodStr, $fullUri, $guzzleOptions, $startTime);
+        }
+
+        // Send the request (async or sync) without middleware
         if ($handler->isAsync) {
             return $handler->executeAsyncRequest($methodStr, $fullUri, $guzzleOptions);
         } else {
             return $handler->executeSyncRequest($methodStr, $fullUri, $guzzleOptions, $startTime);
         }
     }
 
+    /**
+     * Execute the request through the middleware pipeline.
+     *
+     * @param  string  $method  The HTTP method
+     * @param  string  $uri  The full URI
+     * @param  array<string, mixed>  $options  The Guzzle options
+     * @param  float  $startTime  The request start time
+     * @return ResponseInterface|PromiseInterface The response or promise
+     */
+    protected function executeWithMiddleware(
+        string $method,
+        string $uri,
+        array $options,
+        float $startTime,
+    ): ResponseInterface|PromiseInterface {
+        // Create a PSR-7 request from the current state
+        $body = null;
+        if (isset($options['body'])) {
+            $body = $options['body'];
+        } elseif (isset($options['json'])) {
+            $body = json_encode($options['json']);
+        }
+
+        $psrRequest = new GuzzleRequest(
+            $method,
+            $uri,
+            $options['headers'] ?? [],
+            $body
+        );
+
+        // Define the core handler that will be called after all middleware
+        $coreHandler = function (RequestInterface $request) use ($options, $startTime): ResponseInterface|PromiseInterface {
+            // Extract method and URI from the (potentially modified) request
+            $method = $request->getMethod();
+            $uri = (string) $request->getUri();
+
+            // Merge any headers from the modified request back into options
+            $headers = [];
+            foreach ($request->getHeaders() as $name => $values) {
+                $headers[$name] = implode(', ', $values);
+            }
+            $options['headers'] = array_merge($options['headers'] ?? [], $headers);
+
+            // Handle body from modified request
+            $body = $request->getBody();
+            if ($body->getSize() > 0) {
+                $body->rewind();
+                $bodyContents = $body->getContents();
+                $body->rewind();
+
+                // Check if it's JSON
+                $contentType = $request->getHeaderLine('Content-Type');
+                if (str_contains($contentType, 'application/json')) {
+                    $decoded = json_decode($bodyContents, true);
+                    if (json_last_error() === JSON_ERROR_NONE) {
+                        $options['json'] = $decoded;
+                        unset($options['body']);
+                    } else {
+                        $options['body'] = $bodyContents;
+                        unset($options['json']);
+                    }
+                } else {
+                    $options['body'] = $bodyContents;
+                    unset($options['json']);
+                }
+            }
+
+            // Execute the actual request
+            if ($this->isAsync) {
+                return $this->executeAsyncRequest($method, $uri, $options);
+            } else {
+                return $this->executeSyncRequest($method, $uri, $options, $startTime);
+            }
+        };
+
+        // Execute through the middleware pipeline
+        return $this->getMiddlewarePipeline()->handle($psrRequest, $coreHandler);
+    }
+
     /**
      * Sends an HTTP request with the specified parameters.
      *

src/Fetch/Concerns/SupportsMiddleware.php

@@ -0,0 +1,125 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fetch\Concerns;
+
+use Fetch\Http\MiddlewarePipeline;
+use Fetch\Interfaces\ClientHandler;
+use Fetch\Interfaces\MiddlewareInterface;
+
+/**
+ * Trait for adding middleware support to HTTP clients.
+ *
+ * This trait provides methods for managing and executing middleware
+ * that can transform requests and responses.
+ */
+trait SupportsMiddleware
+{
+    /**
+     * The middleware pipeline instance.
+     */
+    protected ?MiddlewarePipeline $middlewarePipeline = null;
+
+    /**
+     * Set multiple middleware at once.
+     *
+     * @param  array<MiddlewareInterface|array{middleware: MiddlewareInterface, priority: int}>  $middleware
+     * @return $this
+     */
+    public function middleware(array $middleware): ClientHandler
+    {
+        $this->middlewarePipeline = new MiddlewarePipeline($middleware);
+
+        return $this;
+    }
+
+    /**
+     * Add a single middleware to the pipeline.
+     *
+     * @param  MiddlewareInterface  $middleware  The middleware to add
+     * @param  int  $priority  Higher priority middleware runs first (default: 0)
+     * @return $this
+     */
+    public function addMiddleware(MiddlewareInterface $middleware, int $priority = 0): ClientHandler
+    {
+        $this->getMiddlewarePipeline()->add($middleware, $priority);
+
+        return $this;
+    }
+
+    /**
+     * Prepend middleware to run first (with highest priority).
+     *
+     * @param  MiddlewareInterface  $middleware  The middleware to prepend
+     * @return $this
+     */
+    public function prependMiddleware(MiddlewareInterface $middleware): ClientHandler
+    {
+        $this->getMiddlewarePipeline()->prepend($middleware);
+
+        return $this;
+    }
+
+    /**
+     * Get the middleware pipeline instance.
+     */
+    public function getMiddlewarePipeline(): MiddlewarePipeline
+    {
+        if ($this->middlewarePipeline === null) {
+            $this->middlewarePipeline = new MiddlewarePipeline;
+        }
+
+        return $this->middlewarePipeline;
+    }
+
+    /**
+     * Check if any middleware is registered.
+     */
+    public function hasMiddleware(): bool
+    {
+        return $this->middlewarePipeline !== null && ! $this->middlewarePipeline->isEmpty();
+    }
+
+    /**
+     * Clear all middleware from the pipeline.
+     *
+     * @return $this
+     */
+    public function clearMiddleware(): ClientHandler
+    {
+        if ($this->middlewarePipeline !== null) {
+            $this->middlewarePipeline->clear();
+        }
+
+        return $this;
+    }
+
+    /**
+     * Conditionally add middleware.
+     *
+     * @param  bool  $condition  The condition to check
+     * @param  callable  $callback  Callback that receives $this and should add middleware
+     * @return $this
+     */
+    public function when(bool $condition, callable $callback): ClientHandler
+    {
+        if ($condition) {
+            $callback($this);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Conditionally add middleware (inverse of when).
+     *
+     * @param  bool  $condition  The condition to check
+     * @param  callable  $callback  Callback that receives $this and should add middleware
+     * @return $this
+     */
+    public function unless(bool $condition, callable $callback): ClientHandler
+    {
+        return $this->when(! $condition, $callback);
+    }
+}

src/Fetch/Http/ClientHandler.php

@@ -11,6 +11,7 @@
 use Fetch\Concerns\ManagesPromises;
 use Fetch\Concerns\ManagesRetries;
 use Fetch\Concerns\PerformsHttpRequests;
+use Fetch\Concerns\SupportsMiddleware;
 use Fetch\Enum\ContentType;
 use Fetch\Enum\Method;
 use Fetch\Interfaces\ClientHandler as ClientHandlerInterface;
@@ -32,7 +33,8 @@ class ClientHandler implements ClientHandlerInterface
         ManagesDebugAndProfiling,
         ManagesPromises,
         ManagesRetries,
-        PerformsHttpRequests;
+        PerformsHttpRequests,
+        SupportsMiddleware;
 
     /**
      * Default options for the request.