[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\Http\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   8  /**
   9   * Represents optional HTTP transport configuration for a single request.
  10   *
  11   * Provides mutable setters for working with timeouts and redirect handling.
  12   *
  13   * @since 0.2.0
  14   *
  15   * @phpstan-type RequestOptionsArrayShape array{
  16   *     timeout?: float|null,
  17   *     connectTimeout?: float|null,
  18   *     maxRedirects?: int|null
  19   * }
  20   *
  21   * @extends AbstractDataTransferObject<RequestOptionsArrayShape>
  22   */
  23  class RequestOptions extends AbstractDataTransferObject
  24  {
  25      public const KEY_TIMEOUT = 'timeout';
  26      public const KEY_CONNECT_TIMEOUT = 'connectTimeout';
  27      public const KEY_MAX_REDIRECTS = 'maxRedirects';
  28      /**
  29       * @var float|null Maximum duration in seconds to wait for the full response.
  30       */
  31      protected ?float $timeout = null;
  32      /**
  33       * @var float|null Maximum duration in seconds to wait for the initial connection.
  34       */
  35      protected ?float $connectTimeout = null;
  36      /**
  37       * @var int|null Maximum number of redirects to follow. 0 disables redirects, null is unspecified.
  38       */
  39      protected ?int $maxRedirects = null;
  40      /**
  41       * Sets the request timeout in seconds.
  42       *
  43       * @since 0.2.0
  44       *
  45       * @param float|null $timeout Timeout in seconds.
  46       * @return void
  47       *
  48       * @throws InvalidArgumentException When timeout is negative.
  49       */
  50      public function setTimeout(?float $timeout): void
  51      {
  52          $this->validateTimeout($timeout, self::KEY_TIMEOUT);
  53          $this->timeout = $timeout;
  54      }
  55      /**
  56       * Sets the connection timeout in seconds.
  57       *
  58       * @since 0.2.0
  59       *
  60       * @param float|null $timeout Connection timeout in seconds.
  61       * @return void
  62       *
  63       * @throws InvalidArgumentException When timeout is negative.
  64       */
  65      public function setConnectTimeout(?float $timeout): void
  66      {
  67          $this->validateTimeout($timeout, self::KEY_CONNECT_TIMEOUT);
  68          $this->connectTimeout = $timeout;
  69      }
  70      /**
  71       * Sets the maximum number of redirects to follow.
  72       *
  73       * Set to 0 to disable redirects, null for unspecified, or a positive integer
  74       * to enable redirects with a maximum count.
  75       *
  76       * @since 0.2.0
  77       *
  78       * @param int|null $maxRedirects Maximum redirects to follow, or 0 to disable, or null for unspecified.
  79       * @return void
  80       *
  81       * @throws InvalidArgumentException When redirect count is negative.
  82       */
  83      public function setMaxRedirects(?int $maxRedirects): void
  84      {
  85          if ($maxRedirects !== null && $maxRedirects < 0) {
  86              throw new InvalidArgumentException('Request option "maxRedirects" must be greater than or equal to 0.');
  87          }
  88          $this->maxRedirects = $maxRedirects;
  89      }
  90      /**
  91       * Gets the request timeout in seconds.
  92       *
  93       * @since 0.2.0
  94       *
  95       * @return float|null Timeout in seconds.
  96       */
  97      public function getTimeout(): ?float
  98      {
  99          return $this->timeout;
 100      }
 101      /**
 102       * Gets the connection timeout in seconds.
 103       *
 104       * @since 0.2.0
 105       *
 106       * @return float|null Connection timeout in seconds.
 107       */
 108      public function getConnectTimeout(): ?float
 109      {
 110          return $this->connectTimeout;
 111      }
 112      /**
 113       * Checks whether redirects are allowed.
 114       *
 115       * @since 0.2.0
 116       *
 117       * @return bool|null True when redirects are allowed (maxRedirects > 0),
 118       *                   false when disabled (maxRedirects = 0),
 119       *                   null when unspecified (maxRedirects = null).
 120       */
 121      public function allowsRedirects(): ?bool
 122      {
 123          if ($this->maxRedirects === null) {
 124              return null;
 125          }
 126          return $this->maxRedirects > 0;
 127      }
 128      /**
 129       * Gets the maximum number of redirects to follow.
 130       *
 131       * @since 0.2.0
 132       *
 133       * @return int|null Maximum redirects or null when not specified.
 134       */
 135      public function getMaxRedirects(): ?int
 136      {
 137          return $this->maxRedirects;
 138      }
 139      /**
 140       * {@inheritDoc}
 141       *
 142       * @since 0.2.0
 143       *
 144       * @return RequestOptionsArrayShape
 145       */
 146      public function toArray(): array
 147      {
 148          $data = [];
 149          if ($this->timeout !== null) {
 150              $data[self::KEY_TIMEOUT] = $this->timeout;
 151          }
 152          if ($this->connectTimeout !== null) {
 153              $data[self::KEY_CONNECT_TIMEOUT] = $this->connectTimeout;
 154          }
 155          if ($this->maxRedirects !== null) {
 156              $data[self::KEY_MAX_REDIRECTS] = $this->maxRedirects;
 157          }
 158          return $data;
 159      }
 160      /**
 161       * {@inheritDoc}
 162       *
 163       * @since 0.2.0
 164       */
 165      public static function fromArray(array $array): self
 166      {
 167          $instance = new self();
 168          if (isset($array[self::KEY_TIMEOUT])) {
 169              $instance->setTimeout((float) $array[self::KEY_TIMEOUT]);
 170          }
 171          if (isset($array[self::KEY_CONNECT_TIMEOUT])) {
 172              $instance->setConnectTimeout((float) $array[self::KEY_CONNECT_TIMEOUT]);
 173          }
 174          if (isset($array[self::KEY_MAX_REDIRECTS])) {
 175              $instance->setMaxRedirects((int) $array[self::KEY_MAX_REDIRECTS]);
 176          }
 177          return $instance;
 178      }
 179      /**
 180       * {@inheritDoc}
 181       *
 182       * @since 0.2.0
 183       */
 184      public static function getJsonSchema(): array
 185      {
 186          return ['type' => 'object', 'properties' => [self::KEY_TIMEOUT => ['type' => ['number', 'null'], 'minimum' => 0, 'description' => 'Maximum duration in seconds to wait for the full response.'], self::KEY_CONNECT_TIMEOUT => ['type' => ['number', 'null'], 'minimum' => 0, 'description' => 'Maximum duration in seconds to wait for the initial connection.'], self::KEY_MAX_REDIRECTS => ['type' => ['integer', 'null'], 'minimum' => 0, 'description' => 'Maximum redirects to follow. 0 disables, null is unspecified.']], 'additionalProperties' => \false];
 187      }
 188      /**
 189       * Validates timeout values.
 190       *
 191       * @since 0.2.0
 192       *
 193       * @param float|null $value Timeout to validate.
 194       * @param string $fieldName Field name for the error message.
 195       *
 196       * @throws InvalidArgumentException When timeout is negative.
 197       */
 198      private function validateTimeout(?float $value, string $fieldName): void
 199      {
 200          if ($value !== null && $value < 0) {
 201              throw new InvalidArgumentException(sprintf('Request option "%s" must be greater than or equal to 0.', $fieldName));
 202          }
 203      }
 204  }