docs: improve comments

docs/classes/Phpolar-CsrfProtection-Http-CsrfRequestCheckMiddleware.html

@@ -127,7 +127,7 @@ <h2 class="phpdocumentor-content__title">
 
     </aside>
 
-            <p class="phpdocumentor-summary">Adds support for CSRF attack mitigation</p>
+            <p class="phpdocumentor-summary">Takes care of request validation logic for CSRF attack mitigation</p>
 
 
 
@@ -167,7 +167,8 @@ <h3 id="toc">
     <span>
                                 &nbsp;: <abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr>    </span>
 </dt>
-<dd>Provide protection against CSRF attack.</dd>
+<dd>Produces a response for an invalid request or
+delegates request handling to the provided handler.</dd>
 
         </dl>
 
@@ -239,19 +240,21 @@ <h4 class="phpdocumentor-element__name" id="method_process">
     <aside class="phpdocumentor-element-found-in">
     <abbr class="phpdocumentor-element-found-in__file" title="Http/CsrfRequestCheckMiddleware.php"><a href="files/http-csrfrequestcheckmiddleware.html"><abbr title="Http/CsrfRequestCheckMiddleware.php">CsrfRequestCheckMiddleware.php</abbr></a></abbr>
     :
-    <span class="phpdocumentor-element-found-in__line">29</span>
+    <span class="phpdocumentor-element-found-in__line">31</span>
 
     </aside>
 
-        <p class="phpdocumentor-summary">Provide protection against CSRF attack.</p>
+        <p class="phpdocumentor-summary">Produces a response for an invalid request or
+delegates request handling to the provided handler.</p>
 
     <code class="phpdocumentor-code phpdocumentor-signature ">
     <span class="phpdocumentor-signature__visibility">public</span>
                     <span class="phpdocumentor-signature__name">process</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Message\ServerRequestInterface">ServerRequestInterface</abbr>&nbsp;</span><span class="phpdocumentor-signature__argument__name">$request</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Server\RequestHandlerInterface">RequestHandlerInterface</abbr>&nbsp;</span><span class="phpdocumentor-signature__argument__name">$handler</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type"><abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr></span></code>
 
-        <section class="phpdocumentor-description"><p>If the request fails the check,
-the provided request handler will be used
-to create the request.</p>
+        <section class="phpdocumentor-description"><p>if the request fails the check,
+this middleware will return a <em>canned response</em>
+with a response that is either <strong>Method Not Allowed</strong>,
+<strong>Bad Request</strong> or <strong>Forbidden</strong>.</p>
 </section>
 
         <h5 class="phpdocumentor-argument-list__heading">Parameters</h5>

docs/classes/Phpolar-CsrfProtection-Http-CsrfResponseFilterMiddleware.html

@@ -169,7 +169,9 @@ <h3 id="toc">
     <span>
                                 &nbsp;: <abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr>    </span>
 </dt>
-<dd>Provide protection against CSRF attack.</dd>
+<dd>Stores a *request validation token* in
+server state and attaches the token to the
+response.</dd>
 
         </dl>
 
@@ -257,19 +259,20 @@ <h4 class="phpdocumentor-element__name" id="method_process">
     <aside class="phpdocumentor-element-found-in">
     <abbr class="phpdocumentor-element-found-in__file" title="Http/CsrfResponseFilterMiddleware.php"><a href="files/http-csrfresponsefiltermiddleware.html"><abbr title="Http/CsrfResponseFilterMiddleware.php">CsrfResponseFilterMiddleware.php</abbr></a></abbr>
     :
-    <span class="phpdocumentor-element-found-in__line">35</span>
+    <span class="phpdocumentor-element-found-in__line">36</span>
 
     </aside>
 
-        <p class="phpdocumentor-summary">Provide protection against CSRF attack.</p>
+        <p class="phpdocumentor-summary">Stores a *request validation token* in
+server state and attaches the token to the
+response.</p>
 
     <code class="phpdocumentor-code phpdocumentor-signature ">
     <span class="phpdocumentor-signature__visibility">public</span>
                     <span class="phpdocumentor-signature__name">process</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Message\ServerRequestInterface">ServerRequestInterface</abbr>&nbsp;</span><span class="phpdocumentor-signature__argument__name">$request</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Server\RequestHandlerInterface">RequestHandlerInterface</abbr>&nbsp;</span><span class="phpdocumentor-signature__argument__name">$handler</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type"><abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr></span></code>
 
-        <section class="phpdocumentor-description"><p>If the request fails the check,
-the provided request handler will be used
-to create the request.</p>
+        <section class="phpdocumentor-description"><p>The stored token SHOULD then be used to validate
+futher requests.</p>
 </section>
 
         <h5 class="phpdocumentor-argument-list__heading">Parameters</h5>

docs/files/http-csrfrequestcheckmiddleware.html

@@ -117,7 +117,7 @@ <h3 id="interfaces_class_traits">
 <dl class="phpdocumentor-table-of-contents">
 
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfRequestCheckMiddleware.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfRequestCheckMiddleware">CsrfRequestCheckMiddleware</abbr></a></dt>
-        <dd>Adds support for CSRF attack mitigation</dd>
+        <dd>Takes care of request validation logic for CSRF attack mitigation</dd>
 
 
     </dl>

docs/js/searchIndex.js

@@ -103,7 +103,7 @@ Search.appendIndex(
         },                {
             "fqsen": "\\Phpolar\\CsrfProtection\\Http\\CsrfRequestCheckMiddleware",
             "name": "CsrfRequestCheckMiddleware",
-            "summary": "Adds\u0020support\u0020for\u0020CSRF\u0020attack\u0020mitigation",
+            "summary": "Takes\u0020care\u0020of\u0020request\u0020validation\u0020logic\u0020for\u0020CSRF\u0020attack\u0020mitigation",
             "url": "classes/Phpolar-CsrfProtection-Http-CsrfRequestCheckMiddleware.html"
         },                {
             "fqsen": "\\Phpolar\\CsrfProtection\\Http\\CsrfRequestCheckMiddleware\u003A\u003A__construct\u0028\u0029",
@@ -113,7 +113,7 @@ Search.appendIndex(
         },                {
             "fqsen": "\\Phpolar\\CsrfProtection\\Http\\CsrfRequestCheckMiddleware\u003A\u003Aprocess\u0028\u0029",
             "name": "process",
-            "summary": "Provide\u0020protection\u0020against\u0020CSRF\u0020attack.",
+            "summary": "Produces\u0020a\u0020response\u0020for\u0020an\u0020invalid\u0020request\u0020or\ndelegates\u0020request\u0020handling\u0020to\u0020the\u0020provided\u0020handler.",
             "url": "classes/Phpolar-CsrfProtection-Http-CsrfRequestCheckMiddleware.html#method_process"
         },                {
             "fqsen": "\\Phpolar\\CsrfProtection\\Http\\CsrfResponseFilterMiddleware",
@@ -128,7 +128,7 @@ Search.appendIndex(
         },                {
             "fqsen": "\\Phpolar\\CsrfProtection\\Http\\CsrfResponseFilterMiddleware\u003A\u003Aprocess\u0028\u0029",
             "name": "process",
-            "summary": "Provide\u0020protection\u0020against\u0020CSRF\u0020attack.",
+            "summary": "Stores\u0020a\u0020\u002Arequest\u0020validation\u0020token\u002A\u0020in\nserver\u0020state\u0020and\u0020attaches\u0020the\u0020token\u0020to\u0020the\nresponse.",
             "url": "classes/Phpolar-CsrfProtection-Http-CsrfResponseFilterMiddleware.html#method_process"
         },                {
             "fqsen": "\\Phpolar\\CsrfProtection\\Http\\ResponseFilterPatternStrategy",

docs/namespaces/phpolar-csrfprotection-http.html

@@ -117,7 +117,7 @@ <h3 id="interfaces_class_traits">
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfProtectionRequestHandler.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfProtectionRequestHandler">CsrfProtectionRequestHandler</abbr></a></dt>
         <dd>Refuses to process an invalid request</dd>
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfRequestCheckMiddleware.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfRequestCheckMiddleware">CsrfRequestCheckMiddleware</abbr></a></dt>
-        <dd>Adds support for CSRF attack mitigation</dd>
+        <dd>Takes care of request validation logic for CSRF attack mitigation</dd>
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfResponseFilterMiddleware.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfResponseFilterMiddleware">CsrfResponseFilterMiddleware</abbr></a></dt>
         <dd>Adds support for CSRF attack mitigation
 by attaching identifiers to the valid

docs/packages/Phpolar-CsrfProtection.html

@@ -121,7 +121,7 @@ <h3 id="interfaces_class_traits">
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfProtectionRequestHandler.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfProtectionRequestHandler">CsrfProtectionRequestHandler</abbr></a></dt>
         <dd>Refuses to process an invalid request</dd>
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfRequestCheckMiddleware.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfRequestCheckMiddleware">CsrfRequestCheckMiddleware</abbr></a></dt>
-        <dd>Adds support for CSRF attack mitigation</dd>
+        <dd>Takes care of request validation logic for CSRF attack mitigation</dd>
             <dt class="phpdocumentor-table-of-contents__entry -class"><a href="classes/Phpolar-CsrfProtection-Http-CsrfResponseFilterMiddleware.html"><abbr title="\Phpolar\CsrfProtection\Http\CsrfResponseFilterMiddleware">CsrfResponseFilterMiddleware</abbr></a></dt>
         <dd>Adds support for CSRF attack mitigation
 by attaching identifiers to the valid

src/Http/CsrfRequestCheckMiddleware.php

@@ -11,7 +11,7 @@
 use Psr\Http\Server\RequestHandlerInterface;
 
 /**
- * Adds support for CSRF attack mitigation
+ * Takes care of request validation logic for CSRF attack mitigation
  */
 class CsrfRequestCheckMiddleware implements MiddlewareInterface
 {
@@ -20,11 +20,13 @@ public function __construct(private RequestHandlerInterface $csrfCheckHandler)
     }
 
     /**
-     * Provide protection against CSRF attack.
+     * Produces a response for an invalid request or
+     * delegates request handling to the provided handler.
      *
-     * If the request fails the check,
-     * the provided request handler will be used
-     * to create the request.
+     * if the request fails the check,
+     * this middleware will return a *canned response*
+     * with a response that is either **Method Not Allowed**,
+     * **Bad Request** or **Forbidden**.
      */
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {

src/Http/CsrfResponseFilterMiddleware.php

@@ -26,11 +26,12 @@ public function __construct(
     }
 
     /**
-     * Provide protection against CSRF attack.
+     * Stores a *request validation token* in
+     * server state and attaches the token to the
+     * response.
      *
-     * If the request fails the check,
-     * the provided request handler will be used
-     * to create the request.
+     * The stored token SHOULD then be used to validate
+     * futher requests.
      */
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {