[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\Http\Collections;
   5  
   6  /**
   7   * Simple collection for managing HTTP headers with case-insensitive access.
   8   *
   9   * This class stores HTTP headers while preserving their original casing
  10   * and provides efficient case-insensitive lookups.
  11   *
  12   * @since 0.1.0
  13   */
  14  class HeadersCollection
  15  {
  16      /**
  17       * @var array<string, list<string>> The headers with original casing.
  18       */
  19      private array $headers = [];
  20      /**
  21       * @var array<string, string> Map of lowercase header names to actual header names.
  22       */
  23      private array $headersMap = [];
  24      /**
  25       * Constructor.
  26       *
  27       * @since 0.1.0
  28       *
  29       * @param array<string, string|list<string>> $headers Initial headers.
  30       */
  31      public function __construct(array $headers = [])
  32      {
  33          foreach ($headers as $name => $value) {
  34              $this->set($name, $value);
  35          }
  36      }
  37      /**
  38       * Gets a specific header value.
  39       *
  40       * @since 0.1.0
  41       *
  42       * @param string $name The header name (case-insensitive).
  43       * @return list<string>|null The header value(s) or null if not found.
  44       */
  45      public function get(string $name): ?array
  46      {
  47          $lowerName = strtolower($name);
  48          if (!isset($this->headersMap[$lowerName])) {
  49              return null;
  50          }
  51          $actualName = $this->headersMap[$lowerName];
  52          return $this->headers[$actualName];
  53      }
  54      /**
  55       * Gets all headers.
  56       *
  57       * @since 0.1.0
  58       *
  59       * @return array<string, list<string>> All headers with their original casing.
  60       */
  61      public function getAll(): array
  62      {
  63          return $this->headers;
  64      }
  65      /**
  66       * Gets header values as a comma-separated string.
  67       *
  68       * @since 0.1.0
  69       *
  70       * @param string $name The header name (case-insensitive).
  71       * @return string|null The header values as a comma-separated string or null if not found.
  72       */
  73      public function getAsString(string $name): ?string
  74      {
  75          $values = $this->get($name);
  76          return $values !== null ? implode(', ', $values) : null;
  77      }
  78      /**
  79       * Checks if a header exists.
  80       *
  81       * @since 0.1.0
  82       *
  83       * @param string $name The header name (case-insensitive).
  84       * @return bool True if the header exists, false otherwise.
  85       */
  86      public function has(string $name): bool
  87      {
  88          return isset($this->headersMap[strtolower($name)]);
  89      }
  90      /**
  91       * Sets a header value, replacing any existing value.
  92       *
  93       * @since 0.1.0
  94       *
  95       * @param string $name The header name.
  96       * @param string|list<string> $value The header value(s).
  97       * @return void
  98       */
  99      private function set(string $name, $value): void
 100      {
 101          if (is_array($value)) {
 102              $normalizedValues = array_values($value);
 103          } else {
 104              // Split comma-separated string into array
 105              $normalizedValues = array_map('trim', explode(',', $value));
 106          }
 107          $lowerName = strtolower($name);
 108          // If header exists with different casing, remove the old casing
 109          if (isset($this->headersMap[$lowerName])) {
 110              $oldName = $this->headersMap[$lowerName];
 111              if ($oldName !== $name) {
 112                  unset($this->headers[$oldName]);
 113              }
 114          }
 115          // Always use the new casing
 116          $this->headers[$name] = $normalizedValues;
 117          $this->headersMap[$lowerName] = $name;
 118      }
 119      /**
 120       * Returns a new instance with the specified header.
 121       *
 122       * @since 0.1.0
 123       *
 124       * @param string $name The header name.
 125       * @param string|list<string> $value The header value(s).
 126       * @return self A new instance with the header.
 127       */
 128      public function withHeader(string $name, $value): self
 129      {
 130          $new = clone $this;
 131          $new->set($name, $value);
 132          return $new;
 133      }
 134  }