Merge remote-tracking branch 'origin/main' into session-backed-enum-support

Author: binaryfire

.gitignore

@@ -6,3 +6,4 @@ composer.lock
 .phpunit.result.cache
 !tests/Foundation/fixtures/hyperf1/composer.lock
 tests/Http/fixtures
+.env

composer.json

@@ -138,6 +138,7 @@
         "symfony/error-handler": "^6.3",
         "symfony/mailer": "^6.2",
         "symfony/process": "^6.2",
+        "symfony/uid": "^7.4",
         "tijsverkoyen/css-to-inline-styles": "^2.2.5"
     },
     "replace": {
@@ -204,6 +205,7 @@
         "hyperf/redis": "~3.1.0",
         "hyperf/testing": "~3.1.0",
         "hyperf/view-engine": "~3.1.0",
+        "hypervel/facade-documenter": "dev-main",
         "league/flysystem": "^3.0",
         "league/flysystem-aws-s3-v3": "^3.0",
         "league/flysystem-google-cloud-storage": "^3.0",

phpstan.neon.dist

@@ -3,7 +3,7 @@
 #
 
 parameters:
-  level: 3
+  level: 5
   parallel:
     jobSize: 20
     maximumNumberOfProcesses: 32
@@ -26,6 +26,8 @@ parameters:
     - %currentWorkingDirectory%/src/support/src/Js.php
     - %currentWorkingDirectory%/src/notifications/src/DatabaseNotification.php
   ignoreErrors:
+    # Framework traits provided for userland - not used internally but intentionally available
+    - '#Trait Hypervel\\[A-Za-z\\\\]+ is used zero times and is not analysed\.#'
     - '#Result of method .* \(void\) is used\.#'
     - '#Unsafe usage of new static#'
     - '#Class [a-zA-Z0-9\\\\_]+ not found.#'

src/api-client/src/ApiClient.php

@@ -26,12 +26,12 @@ class ApiClient
     protected bool $enableMiddleware = true;
 
     /**
-     * @var array<RequestMiddleware|string>
+     * @var array<callable|object|string>
      */
     protected array $requestMiddleware = [];
 
     /**
-     * @var array<ResponseMiddleware|string>
+     * @var array<callable|object|string>
      */
     protected array $responseMiddleware = [];
 

src/api-client/src/ApiRequest.php

@@ -11,6 +11,8 @@
 
 class ApiRequest extends HttpClientRequest
 {
+    use HasContext;
+
     /**
      * Determine if the request data has changed.
      */
@@ -180,6 +182,7 @@ public function withoutHeaders(array $headers): static
     public function withBody(string $body): static
     {
         $this->request = $this->request->withBody(new Stream($body));
+        $this->dataChanged = false;
 
         return $this;
     }

src/api-client/src/ApiResource.php

@@ -9,8 +9,6 @@
 use Hyperf\Contract\Arrayable;
 use Hyperf\Contract\Jsonable;
 use Hyperf\Support\Traits\ForwardsCalls;
-use Hypervel\HttpClient\Request;
-use Hypervel\HttpClient\Response;
 use JsonSerializable;
 use Stringable;
 
@@ -25,8 +23,8 @@ class ApiResource implements Stringable, ArrayAccess, JsonSerializable, Arrayabl
      * Create a new resource instance.
      */
     public function __construct(
-        protected Response $response,
-        protected Request $request
+        protected ApiResponse $response,
+        protected ApiRequest $request
     ) {
     }
 
@@ -73,12 +71,12 @@ public function __call(string $method, array $parameters): mixed
         return $this->forwardCallTo($this->response, $method, $parameters);
     }
 
-    public function getResponse(): Response
+    public function getResponse(): ApiResponse
     {
         return $this->response;
     }
 
-    public function getRequest(): Request
+    public function getRequest(): ApiRequest
     {
         return $this->request;
     }

src/api-client/src/ApiResponse.php

@@ -5,7 +5,63 @@
 namespace Hypervel\ApiClient;
 
 use Hypervel\HttpClient\Response as HttpClientResponse;
+use Psr\Http\Message\StreamInterface;
 
 class ApiResponse extends HttpClientResponse
 {
+    use HasContext;
+
+    public function withStatus(int $code, string $reasonPhrase = ''): static
+    {
+        $this->response = $this->toPsrResponse()
+            ->withStatus($code, $reasonPhrase);
+
+        return $this;
+    }
+
+    public function withProtocolVersion(string $version): static
+    {
+        $this->response = $this->toPsrResponse()
+            ->withProtocolVersion($version);
+
+        return $this;
+    }
+
+    public function hasHeader(string $name): bool
+    {
+        return $this->toPsrResponse()
+            ->hasHeader($name);
+    }
+
+    public function withHeader(string $name, mixed $value): static
+    {
+        $this->response = $this->toPsrResponse()
+            ->withHeader($name, $value);
+
+        return $this;
+    }
+
+    public function withAddedHeader(string $name, mixed $value): static
+    {
+        $this->response = $this->toPsrResponse()
+            ->withAddedHeader($name, $value);
+
+        return $this;
+    }
+
+    public function withoutHeader(string $name): static
+    {
+        $this->response = $this->toPsrResponse()
+            ->withoutHeader($name);
+
+        return $this;
+    }
+
+    public function withBody(StreamInterface $body): static
+    {
+        $this->response = $this->toPsrResponse()
+            ->withBody($body);
+
+        return $this;
+    }
 }

src/api-client/src/HasContext.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\ApiClient;
+
+trait HasContext
+{
+    protected array $context = [];
+
+    /**
+     * Set the API request/response context.
+     */
+    public function withContext(string|array $key, mixed $value = null): static
+    {
+        if (is_array($key)) {
+            $this->context = array_merge($this->context, $key);
+
+            return $this;
+        }
+
+        $this->context[$key] = $value;
+
+        return $this;
+    }
+
+    /**
+     * Get the API request/response context.
+     */
+    public function context(?string $key = null): mixed
+    {
+        if ($key !== null) {
+            return $this->context[$key] ?? null;
+        }
+
+        return $this->context;
+    }
+}

src/api-client/src/PendingRequest.php

@@ -9,6 +9,7 @@
 use Hypervel\HttpClient\PendingRequest as ClientPendingRequest;
 use Hypervel\HttpClient\Request;
 use Hypervel\Support\Facades\Http;
+use Hypervel\Support\Pipeline;
 use Hypervel\Support\Traits\Conditionable;
 use InvalidArgumentException;
 use JsonSerializable;
@@ -34,24 +35,30 @@ class PendingRequest
     protected array $guzzleOptions = [];
 
     /**
-     * @var array<RequestMiddleware|string>
+     * @var array<callable|object|string>
      */
     protected array $requestMiddleware = [];
 
     /**
-     * @var array<ResponseMiddleware|string>
+     * @var array<callable|object|string>
      */
     protected array $responseMiddleware = [];
 
     protected ?ClientPendingRequest $request = null;
 
+    protected Pipeline $pipeline;
+
+    protected static $cachedMiddleware = [];
+
     public function __construct(
         protected ApiClient $client,
+        ?Pipeline $pipeline = null,
     ) {
         $this->resource = $this->client->getResource();
         $this->enableMiddleware = $this->client->getEnableMiddleware();
         $this->requestMiddleware = $this->client->getRequestMiddleware();
         $this->responseMiddleware = $this->client->getResponseMiddleware();
+        $this->pipeline = $pipeline ?? Pipeline::make();
     }
 
     /**
@@ -148,7 +155,7 @@ public function withResource(string $resource): static
             );
         }
 
-        if (! is_subclass_of($resource, ApiResource::class)) {
+        if (! is_subclass_of($resource, ApiResource::class)) { // @phpstan-ignore function.alreadyNarrowedType (validates PHPDoc contract at runtime)
             throw new InvalidArgumentException(
                 sprintf('Resource class `%s` must be a subclass of `%s`', $resource, ApiResource::class)
             );
@@ -236,6 +243,14 @@ public function send(string $method, string $url, array $options = []): ApiResou
         return $this->sendRequest('send', $method, $url, $options);
     }
 
+    /**
+     * Flush the cached middleware instances.
+     */
+    public function flushCache(): void
+    {
+        static::$cachedMiddleware = [];
+    }
+
     /**
      * Provide a dynamic method to pass calls to the pending request.
      */
@@ -255,17 +270,43 @@ protected function sendRequest(): ApiResource
         $request = null;
         $response = $this->getClient()
             ->beforeSending(function (Request $httpRequest) use (&$request) {
-                $request = $httpRequest;
+                $request = new ApiRequest($httpRequest->toPsrRequest());
+                if ($this->enableMiddleware) {
+                    $request = $this->handleMiddlewareRequest($request);
+                }
+                return $request->toPsrRequest();
             })->{$method}(...$arguments);
 
         if ($response instanceof PromiseInterface) {
             throw new InvalidArgumentException('Api client does not support async requests');
         }
 
+        $response = new ApiResponse($response->toPsrResponse());
+
+        if ($this->enableMiddleware) {
+            $response = $this->handleMiddlewareResponse($response);
+        }
+
         return $this->resource::make($response, $request);
     }
 
-    protected function createMiddleware(array $middlewareClasses, array $options): array
+    protected function handleMiddlewareRequest(ApiRequest $request): ApiRequest
+    {
+        return $this->pipeline
+            ->send($request->withContext('options', $this->middlewareOptions))
+            ->through($this->createMiddleware($this->requestMiddleware))
+            ->thenReturn();
+    }
+
+    protected function handleMiddlewareResponse(ApiResponse $response): ApiResponse
+    {
+        return $this->pipeline
+            ->send($response->withContext('options', $this->middlewareOptions))
+            ->through($this->createMiddleware($this->responseMiddleware))
+            ->thenReturn();
+    }
+
+    protected function createMiddleware(array $middlewareClasses): array
     {
         $middleware = [];
         foreach ($middlewareClasses as $value) {
@@ -274,8 +315,11 @@ protected function createMiddleware(array $middlewareClasses, array $options): a
                     sprintf('Middleware class `%s` does not exist', $value)
                 );
             }
-
-            $middleware[] = new $value($this->client->getConfig(), $options);
+            if ($cache = static::$cachedMiddleware[$value] ?? null) {
+                $middleware[] = $cache;
+                continue;
+            }
+            $middleware[] = static::$cachedMiddleware[$value] = new $value($this->client->getConfig());
         }
 
         return $middleware;
@@ -293,18 +337,6 @@ protected function getClient(): ClientPendingRequest
             $request->withOptions($this->guzzleOptions);
         }
 
-        if (! $this->enableMiddleware) {
-            return $request;
-        }
-
-        foreach ($this->createMiddleware($this->requestMiddleware, $this->middlewareOptions) as $middleware) {
-            $request->withRequestMiddleware($middleware);
-        }
-
-        foreach ($this->createMiddleware($this->responseMiddleware, $this->middlewareOptions) as $middleware) {
-            $request->withResponseMiddleware($middleware);
-        }
-
         return $this->request = $request;
     }
 }