feat!: use builders for RequestOptions

Author: stainless-app[bot]

README.md

@@ -105,7 +105,7 @@ Certain errors will be automatically retried 2 times by default, with a short ex
 
 Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
-You can use the `max_retries` option to configure or disable this:
+You can use the `maxRetries` option to configure or disable this:
 
 ```php
 <?php
@@ -118,7 +118,9 @@ $client = new Client(maxRetries: 0);
 
 // Or, configure per-request:
 
-$result = $client->casParser->smartParse(new RequestOptions(maxRetries: 5));
+$result = $client->casParser->smartParse(
+  requestOptions: RequestOptions::with(maxRetries: 5)
+);
 ```
 
 ## Advanced concepts
@@ -129,15 +131,15 @@ $result = $client->casParser->smartParse(new RequestOptions(maxRetries: 5));
 
 You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
 
-Note: the `extra_` parameters of the same name overrides the documented parameters.
+Note: the `extra*` parameters of the same name overrides the documented parameters.
 
 ```php
 <?php
 
 use CasParser\RequestOptions;
 
 $unifiedResponse = $client->casParser->smartParse(
-  new RequestOptions(
+  requestOptions: RequestOptions::with(
     extraQueryParams: ["my_query_parameter" => "value"],
     extraBodyParams: ["my_body_parameter" => "value"],
     extraHeaders: ["my-header" => "value"],

src/Client.php

@@ -32,7 +32,7 @@ public function __construct(?string $apiKey = null, ?string $baseUrl = null)
             'CAS_PARSER_BASE_URL'
         ) ?: 'https://portfolio-parser.api.casparser.in';
 
-        $options = new RequestOptions(
+        $options = RequestOptions::with(
             uriFactory: Psr17FactoryDiscovery::findUriFactory(),
             streamFactory: Psr17FactoryDiscovery::findStreamFactory(),
             requestFactory: Psr17FactoryDiscovery::findRequestFactory(),

src/Core.php

@@ -4,6 +4,6 @@
 
 namespace CasParser\Core;
 
-use CasParser\Core\Implementation\Omittable;
+use CasParser\Core\Implementation\Omit;
 
-const OMIT = Omittable::OMIT;
+const OMIT = Omit::omit;

src/Core/BaseClient.php

@@ -32,6 +32,8 @@ class BaseClient
     protected UriInterface $baseUrl;
 
     /**
+     * @internal
+     *
      * @param array<string, string|int|list<string|int>|null> $headers
      */
     public function __construct(
@@ -108,6 +110,8 @@ protected function authHeaders(): array
     }
 
     /**
+     * @internal
+     *
      * @param string|list<string> $path
      * @param array<string, mixed> $query
      * @param array<string, string|int|list<string|int>|null> $headers
@@ -135,26 +139,31 @@ protected function buildRequest(
         mixed $body,
         RequestOptions|array|null $opts,
     ): array {
-        $opts = array_merge($this->options->toArray(), RequestOptions::parse($opts)->toArray());
-        $options = new RequestOptions(...$opts);
+        $options = RequestOptions::parse($this->options, $opts);
 
         $parsedPath = Util::parsePath($path);
 
         /** @var array<string, mixed> $mergedQuery */
-        $mergedQuery = array_merge_recursive($query, $options->extraQueryParams);
+        $mergedQuery = array_merge_recursive(
+            $query,
+            $options->extraQueryParams ?? [],
+        );
         $uri = Util::joinUri($this->baseUrl, path: $parsedPath, query: $mergedQuery)->__toString();
 
         /** @var array<string, string|list<string>|null> $mergedHeaders */
         $mergedHeaders = [...$this->headers,
             ...$this->authHeaders(),
             ...$headers,
-            ...$options->extraHeaders, ];
+            ...($options->extraHeaders ?? []), ];
 
         $req = ['method' => strtoupper($method), 'path' => $uri, 'query' => $mergedQuery, 'headers' => $mergedHeaders, 'body' => $body];
 
         return [$req, $options];
     }
 
+    /**
+     * @internal
+     */
     protected function followRedirect(
         ResponseInterface $rsp,
         RequestInterface $req
@@ -170,6 +179,8 @@ protected function followRedirect(
     }
 
     /**
+     * @internal
+     *
      * @param bool|int|float|string|resource|\Traversable<mixed>|array<string,
      * mixed,>|null $data
      */

src/Core/Concerns/SdkParams.php

@@ -18,15 +18,7 @@ trait SdkParams
      * @param array<string, mixed>|self|null           $params
      * @param array<string, mixed>|RequestOptions|null $options
      *
-     * @return array{array<string, mixed>, array{
-     *     timeout: float,
-     *     maxRetries: int,
-     *     initialRetryDelay: float,
-     *     maxRetryDelay: float,
-     *     extraHeaders: list<string>,
-     *     extraQueryParams: list<string>,
-     *     extraBodyParams: list<string>,
-     * }}
+     * @return array{array<string, mixed>, RequestOptions}
      */
     public static function parseRequest(array|self|null $params, array|RequestOptions|null $options): array
     {
@@ -40,17 +32,6 @@ public static function parseRequest(array|self|null $params, array|RequestOption
             $opts->maxRetries = 0;
         }
 
-        $opt = $opts->__serialize();
-        if (empty($opt['extraHeaders'])) {
-            unset($opt['extraHeaders']);
-        }
-        if (empty($opt['extraQueryParams'])) {
-            unset($opt['extraQueryParams']);
-        }
-        if (empty($opt['extraBodyParams'])) {
-            unset($opt['extraBodyParams']);
-        }
-
-        return [$dumped, $opt]; // @phpstan-ignore-line
+        return [$dumped, $opts]; // @phpstan-ignore-line
     }
 }

src/Core/Implementation/Omittable.php renamed to src/Core/Implementation/Omit.php

@@ -7,7 +7,7 @@
 /**
  * @internal
  */
-enum Omittable
+enum Omit
 {
-    case OMIT;
+    case omit;
 }

src/RequestOptions.php

@@ -7,7 +7,7 @@
 use CasParser\Core\Attributes\Api as Property;
 use CasParser\Core\Concerns\SdkModel;
 use CasParser\Core\Contracts\BaseModel;
-use CasParser\Core\Implementation\Omittable;
+use CasParser\Core\Implementation\Omit;
 use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\RequestFactoryInterface;
 use Psr\Http\Message\StreamFactoryInterface;
@@ -48,15 +48,15 @@ final class RequestOptions implements BaseModel
     #[Property]
     public float $maxRetryDelay = 8.0;
 
-    /** @var array<string, string|int|list<string|int>|null> $extraHeaders */
-    #[Property]
-    public array $extraHeaders = [];
+    /** @var array<string, string|int|list<string|int>|null>|null $extraHeaders */
+    #[Property(optional: true)]
+    public ?array $extraHeaders;
 
-    /** @var array<string, mixed> $extraQueryParams */
-    #[Property]
-    public array $extraQueryParams = [];
+    /** @var array<string, mixed>|null $extraQueryParams */
+    #[Property(optional: true)]
+    public ?array $extraQueryParams;
 
-    #[Property]
+    #[Property(optional: true)]
     public mixed $extraBodyParams;
 
     #[Property(optional: true)]
@@ -71,12 +71,27 @@ final class RequestOptions implements BaseModel
     #[Property(optional: true)]
     public ?RequestFactoryInterface $requestFactory;
 
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * @param request_opts|null $options
+     */
+    public static function parse(RequestOptions|array|null ...$options): self
+    {
+        $parsed = array_map(static fn ($o) => $o instanceof self ? $o->toArray() : $o ?? [], array: $options);
+
+        return self::with(...array_merge(...$parsed)); // @phpstan-ignore-line
+    }
+
     /**
      * @param array<string, string|int|list<string|int>|null>|null $extraHeaders
      * @param array<string, mixed>|null $extraQueryParams
-     * @param mixed|Omittable $extraBodyParams
+     * @param mixed|Omit $extraBodyParams
      */
-    public function __construct(
+    public static function with(
         ?float $timeout = null,
         ?int $maxRetries = null,
         ?float $initialRetryDelay = null,
@@ -88,40 +103,117 @@ public function __construct(
         ?UriFactoryInterface $uriFactory = null,
         ?StreamFactoryInterface $streamFactory = null,
         ?RequestFactoryInterface $requestFactory = null,
-    ) {
-        $this->initialize();
+    ): self {
+        $obj = new self;
+
+        null !== $timeout && $obj->timeout = $timeout;
+        null !== $maxRetries && $obj->maxRetries = $maxRetries;
+        null !== $initialRetryDelay && $obj->initialRetryDelay = $initialRetryDelay;
+        null !== $maxRetryDelay && $obj->maxRetryDelay = $maxRetryDelay;
+        null !== $extraHeaders && $obj->extraHeaders = $extraHeaders;
+        null !== $extraQueryParams && $obj->extraQueryParams = $extraQueryParams;
+        omit !== $extraBodyParams && $obj->extraBodyParams = $extraBodyParams;
+        null !== $transporter && $obj->transporter = $transporter;
+        null !== $uriFactory && $obj->uriFactory = $uriFactory;
+        null !== $streamFactory && $obj->streamFactory = $streamFactory;
+        null !== $requestFactory && $obj->requestFactory = $requestFactory;
+
+        return $obj;
+    }
+
+    public function withTimeout(float $timeout): self
+    {
+        $obj = clone $this;
+        $obj->timeout = $timeout;
+
+        return $obj;
+    }
+
+    public function withMaxRetries(int $maxRetries): self
+    {
+        $obj = clone $this;
+        $obj->maxRetries = $maxRetries;
+
+        return $obj;
+    }
+
+    public function withInitialRetryDelay(float $initialRetryDelay): self
+    {
+        $obj = clone $this;
+        $obj->initialRetryDelay = $initialRetryDelay;
 
-        null !== $timeout && $this->timeout = $timeout;
-        null !== $maxRetries && $this->maxRetries = $maxRetries;
-        null !== $initialRetryDelay && $this
-            ->initialRetryDelay = $initialRetryDelay
-        ;
-        null !== $maxRetryDelay && $this->maxRetryDelay = $maxRetryDelay;
-        null !== $extraHeaders && $this->extraHeaders = $extraHeaders;
-        null !== $extraQueryParams && $this->extraQueryParams = $extraQueryParams;
-        omit !== $extraBodyParams && $this->extraBodyParams = $extraBodyParams;
-        null !== $transporter && $this->transporter = $transporter;
-        null !== $uriFactory && $this->uriFactory = $uriFactory;
-        null !== $streamFactory && $this->streamFactory = $streamFactory;
-        null !== $requestFactory && $this->requestFactory = $requestFactory;
+        return $obj;
+    }
+
+    public function withMaxRetryDelay(float $maxRetryDelay): self
+    {
+        $obj = clone $this;
+        $obj->maxRetryDelay = $maxRetryDelay;
+
+        return $obj;
     }
 
     /**
-     * @param request_opts|null $options
+     * @param array<string, string|int|list<string|int>|null> $extraHeaders
+     */
+    public function withExtraHeaders(array $extraHeaders): self
+    {
+        $obj = clone $this;
+        $obj->extraHeaders = $extraHeaders;
+
+        return $obj;
+    }
+
+    /**
+     * @param array<string, mixed> $extraQueryParams
      */
-    public static function parse(RequestOptions|array|null $options): self
+    public function withExtraQueryParams(array $extraQueryParams): self
+    {
+        $obj = clone $this;
+        $obj->extraQueryParams = $extraQueryParams;
+
+        return $obj;
+    }
+
+    public function withExtraBodyParams(mixed $extraBodyParams): self
+    {
+        $obj = clone $this;
+        $obj->extraBodyParams = $extraBodyParams;
+
+        return $obj;
+    }
+
+    public function withTransporter(ClientInterface $transporter): self
+    {
+        $obj = clone $this;
+        $obj->transporter = $transporter;
+
+        return $obj;
+    }
+
+    public function withUriFactory(UriFactoryInterface $uriFactory): self
     {
-        if (is_null($options)) {
-            return new self;
-        }
+        $obj = clone $this;
+        $obj->uriFactory = $uriFactory;
 
-        if ($options instanceof self) {
-            return $options;
-        }
+        return $obj;
+    }
+
+    public function withStreamFactory(
+        StreamFactoryInterface $streamFactory
+    ): self {
+        $obj = clone $this;
+        $obj->streamFactory = $streamFactory;
+
+        return $obj;
+    }
 
-        $opts = new self;
-        $opts->__unserialize($options);
+    public function withRequestFactory(
+        RequestFactoryInterface $requestFactory
+    ): self {
+        $obj = clone $this;
+        $obj->requestFactory = $requestFactory;
 
-        return $opts;
+        return $obj;
     }
 }