Docs corrections (#62)

README.md

@@ -39,7 +39,7 @@ middleware and don't interact with each other in any way.
 
 ### `TrustedHeaderProtocolResolver`
 
-Trusted header protocol resolver is setting a server request protocol based on special header you trust
+Trusted header protocol resolver sets a server request protocol based on special header you trust
 such as `X-Forwarded-Proto`.
 
 You can use it if your server is behind a trusted load balancer or a proxy that's always setting the special header
@@ -201,7 +201,8 @@ $middleware = new Redirect($ipValidator, $urlGenerator);
 $middleware = $middleware->toUrl('/login');
 // Or specify route data for redirection:
 $middleware = $middleware->toRoute('auth/login', ['parameter' => 'value']);
-// If you have set a redirect URL with {@see toUrl()}, the middleware ignores the route data, since the URL is a priority.
+// If you have set a redirect URL with "toUrl()" method, the middleware ignores the route data, since the URL is a
+// priority.
 
 $response = $middleware->process($request, $handler);
 ```
@@ -338,9 +339,7 @@ $locales = ['en' => 'en-US', 'ru' => 'ru-RU', 'uz' => 'uz-UZ']
  */
 $middleware = $middleware->withSupportedLocales($locales);
 
-/**
- * Ignore requests which URLs that match `/api**` wildcard pattern.
- */
+// Ignore requests which URLs that match "/api**" wildcard pattern.
 $middleware = $middleware->withIgnoredRequestUrlPatterns(['/api**']);
 
 $response = $middleware->process($request);

src/HttpCache.php

@@ -192,7 +192,7 @@ private function validateCache(ServerRequestInterface $request, ?int $lastModifi
                 PREG_SPLIT_NO_EMPTY,
             );
 
-            // `HTTP_IF_NONE_MATCH` takes precedence over `HTTP_IF_MODIFIED_SINCE`.
+            // "HTTP_IF_NONE_MATCH" takes precedence over "HTTP_IF_MODIFIED_SINCE".
             // https://tools.ietf.org/html/rfc7232#section-3.3
             return $etag !== null && !empty($header) && in_array($etag, $header, true);
         }

src/Locale.php

@@ -45,7 +45,7 @@ final class Locale implements MiddlewareInterface
      * @param ResponseFactoryInterface $responseFactory Response factory used to create redirect responses.
      * @param array $supportedLocales List of supported locales in key-value format such as `['ru' => 'ru_RU', 'uz' => 'uz_UZ']`.
      * @param string[] $ignoredRequestUrlPatterns {@see WildcardPattern Patterns} for ignoring requests with URLs matching.
-     * @param bool $secureCookie If middleware should flag locale cookie as "secure."
+     * @param bool $secureCookie Whether middleware should flag locale cookie as "secure."
      */
     public function __construct(
         private TranslatorInterface $translator,
@@ -299,7 +299,7 @@ public function withSessionName(string $sessionName): self
     /**
      * Return new instance with enabled or disabled saving of locale.
      *
-     * @param bool $enabled If middleware should save locale into session and cookies.
+     * @param bool $enabled Whether middleware should save locale into session and cookies.
      */
     public function withSaveLocale(bool $enabled): self
     {
@@ -335,7 +335,7 @@ public function withIgnoredRequestUrlPatterns(array $patterns): self
     /**
      * Return new instance with enabled or disabled secure cookies.
      *
-     * @param bool $secure If middleware should flag locale cookie as "secure."
+     * @param bool $secure Whether middleware should flag locale cookie as "secure."
      */
     public function withSecureCookie(bool $secure): self
     {

src/TrustedHeaderProtocolResolver.php

@@ -17,7 +17,7 @@
 use function strtolower;
 
 /**
- * Trusted header protocol resolver is setting a server request protocol based on special header you trust
+ * Trusted header protocol resolver sets a server request protocol based on a special header you trust
  * such as `X-Forwarded-Proto`.
  *
  * You can use it if your server is behind a trusted load balancer or a proxy that's always setting the special header

src/TrustedHostsNetworkResolver.php

@@ -44,23 +44,22 @@
  *
  * ```php
  * $trustedHostsNetworkResolver->withAddedTrustedHosts(
- *   // List of secure hosts including `$_SERVER['REMOTE_ADDR']`.
- *   // You can specify IPv4, IPv6, domains, and aliases. See {@see Ip}.
- *   ['1.1.1.1', '2.2.2.1/3', '2001::/32', 'localhost'].
- *   // IP list headers. For advanced handling of headers {@see TrustedHostsNetworkResolver::IP_HEADER_TYPE_RFC7239}.
- *   // Headers containing many sub-elements (e.g. RFC 7239) must also be listed for other relevant types
- *   // (such as host headers), otherwise they will only be used as an IP list.
- *   ['x-forwarded-for', [TrustedHostsNetworkResolver::IP_HEADER_TYPE_RFC7239, 'forwarded']]
- *   // Protocol headers with accepted protocols and corresponding header values. Matching is case-insensitive.
- *   ['front-end-https' => ['https' => 'on']],
- *   // List of headers containing HTTP host.
- *   ['forwarded', 'x-forwarded-for']
- *   // List of headers containing HTTP URL.
- *   ['x-rewrite-url'],
- *   // List of headers containing port number.
- *   ['x-rewrite-port'],
- *   // List of trusted headers. For untrusted hosts, middleware removes these from the request.
- *   ['x-forwarded-for', 'forwarded', ...],
+ *     // List of secure hosts including "$_SERVER['REMOTE_ADDR']".
+ *     hosts: ['1.1.1.1', '2.2.2.1/3', '2001::/32', 'localhost'].
+ *     // IP list headers.
+ *     // Headers containing multiple sub-elements (e.g. RFC 7239) must also be listed for other relevant types
+ *     // (such as host headers), otherwise they will only be used as an IP list.
+ *     ipHeaders: ['x-forwarded-for', [TrustedHostsNetworkResolver::IP_HEADER_TYPE_RFC7239, 'forwarded']]
+ *     // Protocol headers with accepted protocols and corresponding header values. Matching is case-insensitive.
+ *     protocolHeaders: ['front-end-https' => ['https' => 'on']],
+ *     // List of headers containing HTTP host.
+ *     hostHeaders: ['forwarded', 'x-forwarded-for']
+ *     // List of headers containing HTTP URL.
+ *     urlHeaders: ['x-rewrite-url'],
+ *     // List of headers containing port number.
+ *     portHeaders: ['x-rewrite-port'],
+ *     // List of trusted headers. For untrusted hosts, middleware removes these from the request.
+ *     trustedHeaders: ['x-forwarded-for', 'forwarded', ...],
  * );
  * ```
  *
@@ -136,8 +135,9 @@ public function __construct(private ValidatorInterface $validator)
      *
      * @param string[] $hosts List of trusted host IP addresses. The {@see isValidHost()} method could be overwritten in
      * a subclass to allow using domain names with reverse DNS resolving, for example `yiiframework.com`,
-     * `*.yiiframework.com`.
-     * @param array $ipHeaders List of headers containing IP.
+     * `*.yiiframework.com`. You can specify IPv4, IPv6, domains, and aliases. See {@see Ip}.
+     * @param array $ipHeaders List of headers containing IP. For advanced handling of headers see
+     * {@see TrustedHostsNetworkResolver::IP_HEADER_TYPE_RFC7239}.
      * @param array $protocolHeaders List of headers containing protocol. e.g.
      * `['x-forwarded-for' => ['http' => 'http', 'https' => ['on', 'https']]]`.
      * @param string[] $hostHeaders List of headers containing HTTP host.