feat: normalizes response headers

Author: JasonTheAdams

src/Providers/Http/DTO/Response.php

@@ -17,7 +17,7 @@
  *
  * @phpstan-type ResponseArrayShape array{
  *     statusCode: int,
- *     headers: array<string, string|list<string>>,
+ *     headers: array<string, list<string>>,
  *     body?: string|null,
  *     reasonPhrase: string
  * }
@@ -37,10 +37,15 @@ class Response extends AbstractDataTransferObject
     protected int $statusCode;
 
     /**
-     * @var array<string, string|list<string>> The response headers.
+     * @var array<string, list<string>> The response headers.
      */
     protected array $headers;
 
+    /**
+     * @var array<string, string> Map of lowercase header names to actual header names for fast lookup.
+     */
+    protected array $headersMap;
+
     /**
      * @var string|null The response body.
      */
@@ -70,7 +75,8 @@ public function __construct(int $statusCode, array $headers, ?string $body = nul
         }
 
         $this->statusCode = $statusCode;
-        $this->headers = $headers;
+        $this->headers = $this->normalizeHeaderValues($headers);
+        $this->headersMap = $this->buildHeadersMap($this->headers);
         $this->body = $body;
         $this->reasonPhrase = $reasonPhrase;
     }
@@ -92,7 +98,7 @@ public function getStatusCode(): int
      *
      * @since n.e.x.t
      *
-     * @return array<string, string|list<string>> The headers.
+     * @return array<string, list<string>> The headers.
      */
     public function getHeaders(): array
     {
@@ -105,17 +111,29 @@ public function getHeaders(): array
      * @since n.e.x.t
      *
      * @param string $name The header name (case-insensitive).
-     * @return string|list<string>|null The header value(s) or null if not found.
+     * @return list<string>|null The header value(s) or null if not found.
      */
-    public function getHeader(string $name)
+    public function getHeader(string $name): ?array
     {
-        // Case-insensitive header lookup
-        foreach ($this->headers as $key => $value) {
-            if (strcasecmp($key, $name) === 0) {
-                return $value;
-            }
+        $lower = strtolower($name);
+        if (!isset($this->headersMap[$lower])) {
+            return null;
         }
-        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;
     }
 
     /**
@@ -154,6 +172,40 @@ public function isSuccessful(): bool
         return $this->statusCode >= 200 && $this->statusCode < 300;
     }
 
+    /**
+     * Normalizes header values to ensure they are all arrays.
+     *
+     * @since n.e.x.t
+     *
+     * @param array<string, string|list<string>> $headers The headers to normalize.
+     * @return array<string, list<string>> The normalized headers.
+     */
+    private function normalizeHeaderValues(array $headers): array
+    {
+        $normalized = [];
+        foreach ($headers as $name => $value) {
+            $normalized[$name] = is_array($value) ? array_values($value) : [$value];
+        }
+        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 response data as an array.
      *
@@ -199,13 +251,8 @@ public static function getJsonSchema(): array
                 self::KEY_HEADERS => [
                     'type' => 'object',
                     'additionalProperties' => [
-                        'oneOf' => [
-                            ['type' => 'string'],
-                            [
-                                'type' => 'array',
-                                'items' => ['type' => 'string'],
-                            ],
-                        ],
+                        'type' => 'array',
+                        'items' => ['type' => 'string'],
                     ],
                     'description' => 'The response headers.',
                 ],

tests/unit/Providers/Http/HttpTransporterTest.php

@@ -82,7 +82,11 @@ public function testSendGetRequest(): void
         $this->assertInstanceOf(Response::class, $response);
         $this->assertEquals(200, $response->getStatusCode());
         $this->assertEquals('{"success":true}', $response->getBody());
-        $this->assertEquals('application/json', $response->getHeader('Content-Type'));
+        $this->assertEquals(['application/json'], $response->getHeader('Content-Type'));
+        $this->assertEquals('application/json', $response->getHeaderLine('Content-Type'));
+        // Test case-insensitive header lookup
+        $this->assertEquals(['application/json'], $response->getHeader('content-type'));
+        $this->assertEquals('application/json', $response->getHeaderLine('CONTENT-TYPE'));
     }
 
     /**
@@ -112,7 +116,7 @@ public function testSendPostRequestWithBody(): void
         // Assert
         $this->assertEquals(201, $response->getStatusCode());
         $this->assertEquals('{"id":123}', $response->getBody());
-        $this->assertEquals('/resource/123', $response->getHeader('Location'));
+        $this->assertEquals(['/resource/123'], $response->getHeader('Location'));
 
         // Verify the request was sent correctly
         $sentRequests = $this->mockClient->getRequests();