[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  use WordPress\AiClient\Providers\Http\Collections\HeadersCollection;
   9  /**
  10   * Represents an HTTP response.
  11   *
  12   * This class encapsulates HTTP response data that has been converted
  13   * from PSR-7 responses by the HTTP transporter.
  14   *
  15   * @since 0.1.0
  16   *
  17   * @phpstan-type ResponseArrayShape array{
  18   *     statusCode: int,
  19   *     headers: array<string, list<string>>,
  20   *     body?: string|null
  21   * }
  22   *
  23   * @extends AbstractDataTransferObject<ResponseArrayShape>
  24   */
  25  class Response extends AbstractDataTransferObject
  26  {
  27      public const KEY_STATUS_CODE = 'statusCode';
  28      public const KEY_HEADERS = 'headers';
  29      public const KEY_BODY = 'body';
  30      /**
  31       * @var int The HTTP status code.
  32       */
  33      protected int $statusCode;
  34      /**
  35       * @var HeadersCollection The response headers.
  36       */
  37      protected HeadersCollection $headers;
  38      /**
  39       * @var string|null The response body.
  40       */
  41      protected ?string $body;
  42      /**
  43       * Constructor.
  44       *
  45       * @since 0.1.0
  46       *
  47       * @param int $statusCode The HTTP status code.
  48       * @param array<string, string|list<string>> $headers The response headers.
  49       * @param string|null $body The response body.
  50       *
  51       * @throws InvalidArgumentException If the status code is invalid.
  52       */
  53      public function __construct(int $statusCode, array $headers, ?string $body = null)
  54      {
  55          if ($statusCode < 100 || $statusCode >= 600) {
  56              throw new InvalidArgumentException('Invalid HTTP status code: ' . $statusCode);
  57          }
  58          $this->statusCode = $statusCode;
  59          $this->headers = new HeadersCollection($headers);
  60          $this->body = $body;
  61      }
  62      /**
  63       * Creates a deep clone of this response.
  64       *
  65       * Clones the headers collection to ensure the cloned
  66       * response is independent of the original.
  67       *
  68       * @since 0.4.2
  69       */
  70      public function __clone()
  71      {
  72          // Clone headers collection
  73          $this->headers = clone $this->headers;
  74      }
  75      /**
  76       * Gets the HTTP status code.
  77       *
  78       * @since 0.1.0
  79       *
  80       * @return int The status code.
  81       */
  82      public function getStatusCode(): int
  83      {
  84          return $this->statusCode;
  85      }
  86      /**
  87       * Gets the response headers.
  88       *
  89       * @since 0.1.0
  90       *
  91       * @return array<string, list<string>> The headers.
  92       */
  93      public function getHeaders(): array
  94      {
  95          return $this->headers->getAll();
  96      }
  97      /**
  98       * Gets a specific header value.
  99       *
 100       * @since 0.1.0
 101       *
 102       * @param string $name The header name (case-insensitive).
 103       * @return list<string>|null The header value(s) or null if not found.
 104       */
 105      public function getHeader(string $name): ?array
 106      {
 107          return $this->headers->get($name);
 108      }
 109      /**
 110       * Gets header values as a comma-separated string.
 111       *
 112       * @since 0.1.0
 113       *
 114       * @param string $name The header name (case-insensitive).
 115       * @return string|null The header values as a comma-separated string or null if not found.
 116       */
 117      public function getHeaderAsString(string $name): ?string
 118      {
 119          return $this->headers->getAsString($name);
 120      }
 121      /**
 122       * Gets the response body.
 123       *
 124       * @since 0.1.0
 125       *
 126       * @return string|null The body.
 127       */
 128      public function getBody(): ?string
 129      {
 130          return $this->body;
 131      }
 132      /**
 133       * Checks if the response has a header.
 134       *
 135       * @since 0.1.0
 136       *
 137       * @param string $name The header name.
 138       * @return bool True if the header exists, false otherwise.
 139       */
 140      public function hasHeader(string $name): bool
 141      {
 142          return $this->headers->has($name);
 143      }
 144      /**
 145       * Checks if the response indicates success.
 146       *
 147       * @since 0.1.0
 148       *
 149       * @return bool True if status code is 2xx, false otherwise.
 150       */
 151      public function isSuccessful(): bool
 152      {
 153          return $this->statusCode >= 200 && $this->statusCode < 300;
 154      }
 155      /**
 156       * Gets the response data as an array.
 157       *
 158       * Attempts to decode the body as JSON. Returns null if the body
 159       * is empty or not valid JSON.
 160       *
 161       * @since 0.1.0
 162       *
 163       * @return array<string, mixed>|null The decoded data or null.
 164       */
 165      public function getData(): ?array
 166      {
 167          if ($this->body === null || $this->body === '') {
 168              return null;
 169          }
 170          $data = json_decode($this->body, \true);
 171          if (json_last_error() !== \JSON_ERROR_NONE) {
 172              return null;
 173          }
 174          /** @var array<string, mixed>|null $data */
 175          return is_array($data) ? $data : null;
 176      }
 177      /**
 178       * {@inheritDoc}
 179       *
 180       * @since 0.1.0
 181       */
 182      public static function getJsonSchema(): array
 183      {
 184          return ['type' => 'object', 'properties' => [self::KEY_STATUS_CODE => ['type' => 'integer', 'minimum' => 100, 'maximum' => 599, 'description' => 'The HTTP status code.'], self::KEY_HEADERS => ['type' => 'object', 'additionalProperties' => ['type' => 'array', 'items' => ['type' => 'string']], 'description' => 'The response headers.'], self::KEY_BODY => ['type' => ['string', 'null'], 'description' => 'The response body.']], 'required' => [self::KEY_STATUS_CODE, self::KEY_HEADERS]];
 185      }
 186      /**
 187       * {@inheritDoc}
 188       *
 189       * @since 0.1.0
 190       *
 191       * @return ResponseArrayShape
 192       */
 193      public function toArray(): array
 194      {
 195          $data = [self::KEY_STATUS_CODE => $this->statusCode, self::KEY_HEADERS => $this->headers->getAll()];
 196          if ($this->body !== null) {
 197              $data[self::KEY_BODY] = $this->body;
 198          }
 199          return $data;
 200      }
 201      /**
 202       * {@inheritDoc}
 203       *
 204       * @since 0.1.0
 205       */
 206      public static function fromArray(array $array): self
 207      {
 208          static::validateFromArrayData($array, [self::KEY_STATUS_CODE, self::KEY_HEADERS]);
 209          return new self($array[self::KEY_STATUS_CODE], $array[self::KEY_HEADERS], $array[self::KEY_BODY] ?? null);
 210      }
 211  }