Add new class RequestHeaders

CHANGELOG.md

@@ -1,9 +1,12 @@
 # Yii Request Provider Change Log
 
-## 1.1.1 under development
-
+## 1.1.2 under development
 - no changes in this release.
 
+## 1.1.1 December 13, 2024
+
+- New #12: Add `RequestHeaders` clas that provides convenient access to request headers (@uzdevid)
+
 ## 1.1.0 October 28, 2024
 
 - New #11: Add `RequestCookies` class that provides convenient access to request cookies (@hacan359)

README.md

@@ -73,6 +73,28 @@ class MyClass
 }
 ```
 
+### Request headers collection
+
+You can work with headers as follows:
+
+```php
+class MyClass
+{
+  public function __construct(
+    private \Yiisoft\RequestProvider\RequestHeaders $headers
+  ) {}
+
+  public function go(): void
+  {
+    $this->headers->hasHeader('X-Foo');
+    $this->headers->getHeader('X-Foo');
+    $this->headers->getHeaderLine('X-Foo');
+    $this->headers->getHeaders();
+    $this->headers->getFirstHeaders('X-Foo');
+  }
+}
+```
+
 ## Documentation
 
 - [Internals](docs/internals.md)

src/RequestHeaders.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\RequestProvider;
+
+/**
+ * The RequestHeaders class provides utility methods for retrieving and managing HTTP headers
+ * from a request. It uses a RequestProviderInterface implementation to access the current request.
+ */
+final class RequestHeaders {
+    /**
+     * Initializes the RequestHeaders instance with a request provider.
+     *
+     * @param RequestProviderInterface $requestProvider The request provider to access the request.
+     */
+    public function __construct(
+        private readonly RequestProviderInterface $requestProvider
+    ) {
+    }
+
+    /**
+     * Retrieves the value of a specific header as a string. If the header does not exist, returns null.
+     *
+     * @param string $name The name of the header to retrieve.
+     * @return string|null The header value as a string, or null if the header is not present.
+     */
+    public function getHeaderLine(string $name, string|null $default = null): string|null {
+        $request = $this->requestProvider->get();
+        return $request->hasHeader($name) ? $request->getHeaderLine($name) : $default;
+    }
+
+    /**
+     * Retrieves the value(s) of a specific header as an array.
+     *
+     * @param string $name The name of the header to retrieve.
+     * @return string[] An array of header values, or an empty array if the header is not present.
+     */
+    public function getHeader(string $name): array {
+        return $this->requestProvider->get()->getHeader($name);
+    }
+
+    /**
+     * Retrieves all headers as an associative array where the key is the header name
+     * and the value is an array of its values.
+     *
+     * @return string[][] An associative array of all headers.
+     */
+    public function getHeaders(): array {
+        return $this->requestProvider->get()->getHeaders();
+    }
+
+    /**
+     * Retrieves the first value of each header as an associative array where the key is the header name
+     * and the value is the first header value.
+     *
+     * @return string[] An associative array of the first values of all headers.
+     */
+    public function getFirstHeaders(): array {
+        return array_map(static fn(array $lines) => $lines[0], $this->getHeaders());
+    }
+
+    /**
+     * Checks if a specific header is present in the request.
+     *
+     * @param string $name The name of the header to check.
+     * @return bool True if the header is present, false otherwise.
+     */
+    public function hasHeader(string $name): bool {
+        return $this->requestProvider->get()->hasHeader($name);
+    }
+}

tests/RequestHeadersTest.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\RequestProvider\Tests;
+
+use PHPUnit\Framework\MockObject\Exception;
+use PHPUnit\Framework\TestCase;
+use Psr\Http\Message\ServerRequestInterface;
+use Yiisoft\RequestProvider\RequestHeaders;
+use Yiisoft\RequestProvider\RequestProviderInterface;
+
+final class RequestHeadersTest extends TestCase {
+    private const HEADER_NAME = 'test';
+    private const HEADER_VALUE = 'value';
+
+    /**
+     * @return void
+     * @throws Exception
+     */
+    public function testGetHeaderLine(): void {
+        $requestHeaders = $this->createRequestHeaders([self::HEADER_NAME => [self::HEADER_VALUE]]);
+
+        $this->assertSame(self::HEADER_VALUE, $requestHeaders->getHeaderLine(self::HEADER_NAME));
+    }
+
+    /**
+     * @return void
+     * @throws Exception
+     */
+    public function testGetHeader(): void {
+        $requestHeaders = $this->createRequestHeaders([self::HEADER_NAME => [self::HEADER_VALUE]]);
+
+        $this->assertSame([self::HEADER_VALUE], $requestHeaders->getHeader(self::HEADER_NAME));
+    }
+
+    /**
+     * @return void
+     * @throws Exception
+     */
+    public function testGetHeaders(): void {
+        $requestHeaders = $this->createRequestHeaders([self::HEADER_NAME => [self::HEADER_VALUE]]);
+
+        $this->assertSame([self::HEADER_NAME => [self::HEADER_VALUE]], $requestHeaders->getHeaders());
+    }
+
+    /**
+     * @return void
+     * @throws Exception
+     */
+    public function testGetFirstHeader(): void {
+        $requestHeaders = $this->createRequestHeaders([self::HEADER_NAME => [self::HEADER_VALUE]]);
+
+        $this->assertSame([self::HEADER_NAME => self::HEADER_VALUE], $requestHeaders->getFirstHeaders());
+    }
+
+    /**
+     * @return void
+     * @throws Exception
+     */
+    public function testHasHeader(): void {
+        $requestHeaders = $this->createRequestHeaders([self::HEADER_NAME => [self::HEADER_VALUE]]);
+
+        $this->assertTrue($requestHeaders->hasHeader(self::HEADER_NAME));
+        $this->assertFalse($requestHeaders->hasHeader('non-exist'));
+    }
+
+    /**
+     * @param array $headers
+     * @return RequestHeaders
+     * @throws Exception
+     */
+    private function createRequestHeaders(array $headers = []): RequestHeaders {
+        /** @var ServerRequestInterface $serverRequestMock */
+        $serverRequestMock = $this->createMock(ServerRequestInterface::class);
+        $serverRequestMock
+            ->method('getHeaderLine')
+            ->willReturnCallback(fn(string $name): string => $headers[$name][0] ?? null);
+
+        $serverRequestMock
+            ->method('getHeader')
+            ->willReturnCallback(fn(string $name): array => $headers[$name] ?? []);
+
+        $serverRequestMock
+            ->method('getHeaders')
+            ->willReturnCallback(fn(): array => $headers);
+
+        $serverRequestMock
+            ->method('hasHeader')
+            ->willReturnCallback(fn(string $name) => array_key_exists($name, $headers));
+
+        /** @var RequestProviderInterface $requestProvider */
+        $requestProvider = $this->createMock(RequestProviderInterface::class);
+        $requestProvider->method('get')->willReturn($serverRequestMock);
+
+        return new RequestHeaders($requestProvider);
+    }
+}