feat: improves request header handling

Author: JasonTheAdams

src/Providers/Http/DTO/Request.php

@@ -5,6 +5,7 @@
 namespace WordPress\AiClient\Providers\Http\DTO;
 
 use InvalidArgumentException;
+use JsonException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
 
@@ -47,6 +48,11 @@ class Request extends AbstractDataTransferObject
      */
     protected array $headers;
 
+    /**
+     * @var array<string, string> Map of lowercase header names to actual header names for fast lookup.
+     */
+    protected array $headersMap;
+
     /**
      * @var string|array<string, mixed>|null The request data.
      */
@@ -73,6 +79,7 @@ public function __construct(HttpMethodEnum $method, string $uri, array $headers
         $this->method = $method;
         $this->uri = $uri;
         $this->headers = $this->normalizeHeaders($headers);
+        $this->headersMap = $this->buildHeadersMap($this->headers);
         $this->data = $data;
     }
 
@@ -120,6 +127,50 @@ public function getHeaders(): array
         return $this->headers;
     }
 
+    /**
+     * Gets a specific header value.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $name The header name (case-insensitive).
+     * @return list<string>|null The header value(s) or null if not found.
+     */
+    public function getHeader(string $name): ?array
+    {
+        $lower = strtolower($name);
+        if (!isset($this->headersMap[$lower])) {
+            return null;
+        }
+        return $this->headers[$this->headersMap[$lower]];
+    }
+
+    /**
+     * Gets the first value of a specific header.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $name The header name (case-insensitive).
+     * @return string|null The first header value or null if not found.
+     */
+    public function getHeaderLine(string $name): ?string
+    {
+        $values = $this->getHeader($name);
+        return $values !== null ? implode(', ', $values) : null;
+    }
+
+    /**
+     * Checks if a header exists.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $name The header name (case-insensitive).
+     * @return bool True if the header exists, false otherwise.
+     */
+    public function hasHeader(string $name): bool
+    {
+        return isset($this->headersMap[strtolower($name)]);
+    }
+
     /**
      * Gets the request body.
      *
@@ -176,12 +227,8 @@ public function getBody(): ?string
      */
     private function getContentType(): ?string
     {
-        foreach ($this->headers as $name => $values) {
-            if (strcasecmp($name, 'Content-Type') === 0) {
-                return $values[0] ?? null;
-            }
-        }
-        return null;
+        $values = $this->getHeader('Content-Type');
+        return $values !== null ? $values[0] : null;
     }
 
     /**
@@ -231,6 +278,23 @@ private function normalizeHeaders(array $headers): array
         return $normalized;
     }
 
+    /**
+     * Builds a map of lowercase header names to actual header names.
+     *
+     * @since n.e.x.t
+     *
+     * @param array<string, list<string>> $headers The headers.
+     * @return array<string, string> The headers map.
+     */
+    private function buildHeadersMap(array $headers): array
+    {
+        $map = [];
+        foreach (array_keys($headers) as $name) {
+            $map[strtolower($name)] = $name;
+        }
+        return $map;
+    }
+
     /**
      * Gets the request data.
      *

tests/unit/Providers/Http/HttpTransporterTest.php

@@ -236,6 +236,36 @@ public function testSendPostRequestWithArrayDataAsForm(): void
         $this->assertEquals('name=test&value=123', (string) $sentRequest->getBody());
     }
 
+    /**
+     * Tests case-insensitive header access in Request.
+     *
+     * @return void
+     */
+    public function testRequestCaseInsensitiveHeaders(): void
+    {
+        // Arrange
+        $headers = [
+            'Content-Type' => 'application/json',
+            'X-Custom-Header' => 'value',
+        ];
+        $request = new Request(HttpMethodEnum::GET(), 'https://api.example.com', $headers);
+
+        // Assert - getHeader
+        $this->assertEquals(['application/json'], $request->getHeader('Content-Type'));
+        $this->assertEquals(['application/json'], $request->getHeader('content-type'));
+        $this->assertEquals(['application/json'], $request->getHeader('CONTENT-TYPE'));
+
+        // Assert - getHeaderLine
+        $this->assertEquals('application/json', $request->getHeaderLine('Content-Type'));
+        $this->assertEquals('application/json', $request->getHeaderLine('content-type'));
+
+        // Assert - hasHeader
+        $this->assertTrue($request->hasHeader('Content-Type'));
+        $this->assertTrue($request->hasHeader('content-type'));
+        $this->assertTrue($request->hasHeader('X-CUSTOM-HEADER'));
+        $this->assertFalse($request->hasHeader('Non-Existent'));
+    }
+
     /**
      * Tests using discovery when no dependencies provided.
      *