chore: intuitively order union types

Author: stainless-app[bot]

.php-cs-fixer.dist.php

@@ -7,5 +7,11 @@
 return (new Config())
     ->setParallelConfig(ParallelConfigFactory::detect())
     ->setFinder(Finder::create()->in([__DIR__.'/src', __DIR__.'/tests']))
-    ->setRules(['@PhpCsFixer' => true, 'phpdoc_align' => false, 'new_with_parentheses' => ['named_class' => false]])
+    ->setRules([
+        '@PhpCsFixer' => true,
+        'phpdoc_align' => false,
+        'new_with_parentheses' => ['named_class' => false],
+        'ordered_types' => ['null_adjustment' => 'always_last', 'sort_algorithm' => 'none'],
+        'phpdoc_types_order' => ['null_adjustment' => 'always_last', 'sort_algorithm' => 'none'],
+    ])
 ;

src/Contracts/CrawlContract.php

@@ -21,7 +21,7 @@ public function retrieveResults(
      * @param int $depth Maximum crawl depth from starting URL
      * @param bool $extractionMode Use AI extraction (true) or markdown conversion (false)
      * @param int $maxPages Maximum number of pages to crawl
-     * @param null|string $prompt Extraction prompt (required if extraction_mode is true)
+     * @param string|null $prompt Extraction prompt (required if extraction_mode is true)
      * @param bool $renderHeavyJs Enable heavy JavaScript rendering
      * @param Rules $rules
      * @param mixed $schema Output schema for extraction

src/Contracts/FeedbackContract.php

@@ -12,7 +12,7 @@ interface FeedbackContract
     /**
      * @param int $rating Rating score
      * @param string $requestID Request to provide feedback for
-     * @param null|string $feedbackText Optional feedback comments
+     * @param string|null $feedbackText Optional feedback comments
      */
     public function submit(
         $rating,

src/Core/Attributes/Api.php

@@ -14,20 +14,20 @@
 final class Api
 {
     /**
-     * @var null|class-string<ConverterSource>|Converter|string
+     * @var class-string<ConverterSource>|Converter|string|null
      */
-    public readonly null|Converter|string $type;
+    public readonly Converter|string|null $type;
 
     /**
-     * @param null|class-string<ConverterSource>|Converter|string $type
-     * @param null|class-string<ConverterSource>|Converter        $enum
-     * @param null|class-string<ConverterSource>|Converter|string $union
+     * @param class-string<ConverterSource>|Converter|string|null $type
+     * @param class-string<ConverterSource>|Converter|null        $enum
+     * @param class-string<ConverterSource>|Converter|string|null $union
      */
     public function __construct(
         public readonly ?string $apiName = null,
-        null|Converter|string $type = null,
-        null|Converter|string $enum = null,
-        null|Converter|string $union = null,
+        Converter|string|null $type = null,
+        Converter|string|null $enum = null,
+        Converter|string|null $union = null,
         public readonly bool $nullable = false,
         public readonly bool $optional = false,
     ) {

src/Core/BaseClient.php

@@ -29,7 +29,7 @@ class BaseClient
     protected ClientInterface $transporter;
 
     /**
-     * @param array<string, null|int|list<int|string>|string> $headers
+     * @param array<string, string|int|list<string|int>|null> $headers
      */
     public function __construct(
         protected array $headers,
@@ -45,13 +45,13 @@ public function __construct(
     }
 
     /**
-     * @param list<mixed>|string $path
+     * @param string|list<mixed> $path
      * @param array<string, mixed> $query
      * @param array<string, mixed> $headers
      */
     public function request(
         string $method,
-        array|string $path,
+        string|array $path,
         array $query = [],
         array $headers = [],
         mixed $body = null,
@@ -88,27 +88,27 @@ protected function authHeaders(): array
     }
 
     /**
-     * @param list<string>|string $path
+     * @param string|list<string> $path
      * @param array<string, mixed> $query
-     * @param array<string, null|int|list<int|string>|string> $headers
-     * @param null|array{
-     *   timeout?: null|float,
-     *   maxRetries?: null|int,
-     *   initialRetryDelay?: null|float,
-     *   maxRetryDelay?: null|float,
-     *   extraHeaders?: null|list<string>,
-     *   extraQueryParams?: null|list<string>,
-     *   extraBodyParams?: null|list<string>,
-     * }|RequestOptions $opts
+     * @param array<string, string|int|list<string|int>|null> $headers
+     * @param array{
+     *   timeout?: float|null,
+     *   maxRetries?: int|null,
+     *   initialRetryDelay?: float|null,
+     *   maxRetryDelay?: float|null,
+     *   extraHeaders?: list<string>|null,
+     *   extraQueryParams?: list<string>|null,
+     *   extraBodyParams?: list<string>|null,
+     * }|RequestOptions|null $opts
      *
      * @return array{RequestInterface, RequestOptions}
      */
     protected function buildRequest(
         string $method,
-        array|string $path,
+        string|array $path,
         array $query,
         array $headers,
-        null|array|RequestOptions $opts,
+        array|RequestOptions|null $opts,
     ): array {
         $opts = [...$this->options->__serialize(), ...RequestOptions::parse($opts)->__serialize()];
         $options = new RequestOptions(...$opts);
@@ -119,7 +119,7 @@ protected function buildRequest(
         $mergedQuery = array_merge_recursive($query, $options->extraQueryParams);
         $uri = Util::joinUri($this->baseUrl, path: $parsedPath, query: $mergedQuery);
 
-        /** @var array<string, list<string>|string> $mergedHeaders */
+        /** @var array<string, string | list<string>> $mergedHeaders */
         $mergedHeaders = [...$this->headers,
             ...$this->authHeaders(),
             ...$headers,
@@ -146,9 +146,9 @@ protected function followRedirect(
     }
 
     /**
-     * @param null|array<string, mixed>|bool|float|int|resource|string|\Traversable<
+     * @param bool|int|float|string|array<string, mixed>|resource|\Traversable<
      *   mixed
-     * > $data
+     * >|null $data
      */
     protected function sendRequest(
         RequestInterface $req,

src/Core/Concerns/SdkParams.php

@@ -14,8 +14,8 @@
 trait SdkParams
 {
     /**
-     * @param null|array<string, mixed>|self           $params
-     * @param null|array<string, mixed>|RequestOptions $options
+     * @param array<string, mixed>|self|null           $params
+     * @param array<string, mixed>|RequestOptions|null $options
      *
      * @return array{array<string, mixed>, array{
      *     timeout: float,
@@ -27,7 +27,7 @@ trait SdkParams
      *     extraBodyParams: list<string>,
      * }}
      */
-    public static function parseRequest(null|array|self $params, null|array|RequestOptions $options): array
+    public static function parseRequest(array|self|null $params, array|RequestOptions|null $options): array
     {
         $converter = self::converter();
         $state = new DumpState;

src/Core/Conversion/Concerns/ArrayOf.php

@@ -15,12 +15,12 @@
  */
 trait ArrayOf
 {
-    private readonly null|Converter|ConverterSource|string $type;
+    private readonly Converter|ConverterSource|string|null $type;
 
     public function __construct(
-        null|Converter|ConverterSource|string $type = null,
-        null|Converter|ConverterSource|string $enum = null,
-        null|Converter|ConverterSource|string $union = null,
+        Converter|ConverterSource|string|null $type = null,
+        Converter|ConverterSource|string|null $enum = null,
+        Converter|ConverterSource|string|null $union = null,
         private readonly bool $nullable = false,
     ) {
         $this->type = $type ?? $enum ?? $union;

src/Core/Conversion/EnumOf.php

@@ -15,7 +15,7 @@ final class EnumOf implements Converter
     private readonly string $type;
 
     /**
-     * @param list<null|bool|float|int|string> $members
+     * @param list<bool|float|int|string|null> $members
      */
     public function __construct(private readonly array $members)
     {

src/Core/Conversion/PropertyInfo.php

@@ -46,9 +46,9 @@ public function __construct(public readonly \ReflectionProperty $property)
     }
 
     /**
-     * @param null|array<int|string,string>|Converter|ConverterSource|\ReflectionType|string $type
+     * @param array<int|string,string>|Converter|ConverterSource|\ReflectionType|string|null $type
      */
-    private static function parse(null|array|Converter|ConverterSource|\ReflectionType|string $type): Converter|ConverterSource|string
+    private static function parse(array|Converter|ConverterSource|\ReflectionType|string|null $type): Converter|ConverterSource|string
     {
         if (is_string($type) || $type instanceof Converter) {
             return $type;

src/Core/Conversion/UnionOf.php

@@ -77,7 +77,7 @@ public function dump(mixed $value, DumpState $state): mixed
 
     private function resolveVariant(
         mixed $value,
-    ): null|Converter|ConverterSource|string {
+    ): Converter|ConverterSource|string|null {
         if ($value instanceof BaseModel) {
             return $value::class;
         }