Add phpdoc comment, add doc to readme and changelog

CHANGELOG.md

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

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

@@ -4,48 +4,66 @@
 
 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 {
     /**
-     * @param RequestProviderInterface $requestProvider
+     * 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
     ) {
     }
 
     /**
-     * @param string $name
-     * @return string|null
+     * 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 $default = null): string|null {
         return $this->requestProvider->get()->hasHeader($name) ? $this->requestProvider->get()->getHeaderLine($name) : $default;
     }
 
     /**
-     * @param string $name
-     * @return array
+     * Retrieves the value(s) of a specific header as an array.
+     *
+     * @param string $name The name of the header to retrieve.
+     * @return array 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);
     }
 
     /**
-     * @return array
+     * 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();
     }
 
     /**
-     * @return array
+     * 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());
     }
 
     /**
-     * @param string $name
-     * @return bool
+     * 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);