sebastian-meyer
/
psr-15
mirror of https://github.com/opencultureconsulting/psr-15.git
2
0
Fork 0
Code Issues

Update documentation

This commit is contained in:
Sebastian Meyer 2024-09-07 18:52:50 +02:00
parent d81226031c
commit 02eb93bf3b
16 changed files with 189 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
.phpdoc/guide/changelog.rst
View File

@ -6,6 +6,19 @@ Changelog
.. sidebar:: Table of Contents .. sidebar:: Table of Contents
.. contents:: .. contents::
v1.2.0
======
**Minor Changes:**
* Added a `Warning` header to identify response messages from converted exceptions
* Removed the option to provide an exit status to :php:method:`OCC\PSR15\QueueRequestHandler::respond()`
* Added Composer command for development tools (PHP Mess Detector, Psalm Taint Analysis)
**Maintencance:**
* Updated dependencies
v1.1.0 v1.1.0
====== ======

6
.phpdoc/guide/overview/queuerequesthandler.rst
View File

@ -97,12 +97,10 @@ implements `Psr\Http\Message\ResponseInterface`.
In case of an error the request handler catches any exception and creates a response with the exception code as status In case of an error the request handler catches any exception and creates a response with the exception code as status
code (if it's within the valid range of HTTP status codes, otherwise it's set to `500 (Internal Server Error)`), and code (if it's within the valid range of HTTP status codes, otherwise it's set to `500 (Internal Server Error)`), and
the exception message as body. the exception message as body. Such a response can be identified by having a `Warning` header set including the error
code and the affected middleware.
Sending the Response Sending the Response
-------------------- --------------------
Sending the final response to the client is as easy as calling :php:method:`OCC\PSR15\QueueRequestHandler::respond()`. Sending the final response to the client is as easy as calling :php:method:`OCC\PSR15\QueueRequestHandler::respond()`.
Optionally, you can provide an exit code as argument (an integer in the range `0` to `254`). If you do so, script
execution is stopped after sending out the response and the given exit status is set. The status `0` means the request
was handled successfully, every other status is considered an error.

8
.phpdoc/template/index.html.twig
View File

@ -19,9 +19,11 @@
your own middleware, but you can just as well use any middleware that implements the middleware interface specified your own middleware, but you can just as well use any middleware that implements the middleware interface specified
by PSR-15 (e.g. from the awesome <a href="https://github.com/middlewares">PSR-15 HTTP Middlewares</a> project).</p> by PSR-15 (e.g. from the awesome <a href="https://github.com/middlewares">PSR-15 HTTP Middlewares</a> project).</p>
<p>All components of this package follow the highest coding standards of <a href="https://phpstan.org/">PHPStan</a> <p>All components of this package follow the highest coding standards of <a href="https://psalm.dev/">Psalm</a>,
and <a href="https://psalm.dev/">Psalm</a>, and comply to <a href="https://www.php-fig.org/psr/psr-12/">PSR-12</a> <a href="https://phpstan.org/">PHPStan</a>, <a href="https://phpmd.org/">PHP Mess Detector</a>,
code style guidelines to make sure they can be combined and easily re-used in other projects.</p> <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer/">PHP_CodeSniffer</a>, and comply to
<a href="https://www.php-fig.org/psr/psr-12/">PSR-12</a> code style guidelines to make sure they can be combined
and easily re-used in other projects.</p>
<h3 id="toc">Table of Contents</h3> <h3 id="toc">Table of Contents</h3>

43
doc/classes/OCC-PSR15-QueueRequestHandler.html
View File

@ -184,9 +184,9 @@
<aside class="phpdocumentor-element-found-in"> <aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr> <abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr>
: :
<span class="phpdocumentor-element-found-in__line">54</span> <span class="phpdocumentor-element-found-in__line">53</span>
<a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.54" class="phpdocumentor-element-found-in__source" data-line="54" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a> <a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.53" class="phpdocumentor-element-found-in__source" data-line="53" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a>
</aside> </aside>
<p class="phpdocumentor-summary">A queue-based PSR-15 HTTP Server Request Handler.</p> <p class="phpdocumentor-summary">A queue-based PSR-15 HTTP Server Request Handler.</p>
@ -442,9 +442,9 @@
<aside class="phpdocumentor-element-found-in"> <aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr> <abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr>
: :
<span class="phpdocumentor-element-found-in__line">225</span> <span class="phpdocumentor-element-found-in__line">215</span>
<a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.225" class="phpdocumentor-element-found-in__source" data-line="225" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a> <a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.215" class="phpdocumentor-element-found-in__source" data-line="215" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a>
</aside> </aside>
<p class="phpdocumentor-summary">Create a queue-based PSR-15 HTTP Server Request Handler.</p> <p class="phpdocumentor-summary">Create a queue-based PSR-15 HTTP Server Request Handler.</p>
@ -490,9 +490,9 @@
<aside class="phpdocumentor-element-found-in"> <aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr> <abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr>
: :
<span class="phpdocumentor-element-found-in__line">239</span> <span class="phpdocumentor-element-found-in__line">229</span>
<a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.239" class="phpdocumentor-element-found-in__source" data-line="239" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a> <a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.229" class="phpdocumentor-element-found-in__source" data-line="229" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a>
</aside> </aside>
<p class="phpdocumentor-summary">Allow the request handler to be invoked directly.</p> <p class="phpdocumentor-summary">Allow the request handler to be invoked directly.</p>
@ -546,9 +546,9 @@
<aside class="phpdocumentor-element-found-in"> <aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr> <abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr>
: :
<span class="phpdocumentor-element-found-in__line">94</span> <span class="phpdocumentor-element-found-in__line">93</span>
<a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.94" class="phpdocumentor-element-found-in__source" data-line="94" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a> <a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.93" class="phpdocumentor-element-found-in__source" data-line="93" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a>
</aside> </aside>
<p class="phpdocumentor-summary">Handles a request by invoking a queue of middlewares.</p> <p class="phpdocumentor-summary">Handles a request by invoking a queue of middlewares.</p>
@ -604,16 +604,16 @@
<aside class="phpdocumentor-element-found-in"> <aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr> <abbr class="phpdocumentor-element-found-in__file" title="src/QueueRequestHandler.php"><a href="files/src-queuerequesthandler.html"><abbr title="src/QueueRequestHandler.php">QueueRequestHandler.php</abbr></a></abbr>
: :
<span class="phpdocumentor-element-found-in__line">141</span> <span class="phpdocumentor-element-found-in__line">142</span>
<a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.141" class="phpdocumentor-element-found-in__source" data-line="141" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a> <a href="classes/OCC-PSR15-QueueRequestHandler.html#source-view.142" class="phpdocumentor-element-found-in__source" data-line="142" data-modal="source-view" data-src="files/src/QueueRequestHandler.php.txt"></a>
</aside> </aside>
<p class="phpdocumentor-summary">Return the current response to the client.</p> <p class="phpdocumentor-summary">Return the current response to the client.</p>
<code class="phpdocumentor-code phpdocumentor-signature "> <code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span> <span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">respond</span><span>(</span><span class="phpdocumentor-signature__argument"><span>[</span><span class="phpdocumentor-signature__argument__return-type">int|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$exitCode</span><span> = </span><span class="phpdocumentor-signature__argument__default-value">null</span><span> ]</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">void</span></code> <span class="phpdocumentor-signature__name">respond</span><span>(</span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">void</span></code>
<div class="phpdocumentor-label-line"> <div class="phpdocumentor-label-line">
<div class="phpdocumentor-label phpdocumentor-label--success"><span>API</span><span>Yes</span></div> <div class="phpdocumentor-label phpdocumentor-label--success"><span>API</span><span>Yes</span></div>
@ -621,20 +621,7 @@
</div> </div>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$exitCode</span>
: <span class="phpdocumentor-signature__argument__return-type">int|null</span>
= <span class="phpdocumentor-signature__argument__default-value">null</span> </dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>Exit status after sending out the response or NULL to continue</p>
<p>Must be in the range 0 to 254. The status 0 is used to terminate the program successfully.</p>
</section>
</dd>
</dl>
<h5 class="phpdocumentor-tag-list__heading" id="tags"> <h5 class="phpdocumentor-tag-list__heading" id="tags">
Tags Tags
@ -771,9 +758,9 @@
<li class="phpdocumentor-on-this-page-section__title">Properties</li> <li class="phpdocumentor-on-this-page-section__title">Properties</li>
<li> <li>
<ul class="phpdocumentor-list -clean"> <ul class="phpdocumentor-list -clean">
<li class=""><a href="classes/OCC-PSR15-QueueRequestHandler.html#property_queue">$queue</li> <li class=""><a href="classes/OCC-PSR15-QueueRequestHandler.html#property_queue">$queue</a></li>
<li class=""><a href="classes/OCC-PSR15-QueueRequestHandler.html#property_request">$request</li> <li class=""><a href="classes/OCC-PSR15-QueueRequestHandler.html#property_request">$request</a></li>
<li class=""><a href="classes/OCC-PSR15-QueueRequestHandler.html#property_response">$response</li> <li class=""><a href="classes/OCC-PSR15-QueueRequestHandler.html#property_response">$response</a></li>
</ul> </ul>
</li> </li>

34
doc/files/src/QueueRequestHandler.php.txt
View File

@ -38,7 +38,6 @@ use function filter_var;
use function get_debug_type; use function get_debug_type;
use function header; use function header;
use function headers_sent; use function headers_sent;
use function is_null;
use function sprintf; use function sprintf;
/** /**
@ -110,12 +109,18 @@ class QueueRequestHandler implements RequestHandler
'max_range' => 599 'max_range' => 599
] ]
]; ];
$statusCode = filter_var($exception->getCode(), FILTER_VALIDATE_INT, $options);
$this->response = new GuzzleResponse( $this->response = new GuzzleResponse(
$statusCode, filter_var($exception->getCode(), FILTER_VALIDATE_INT, $options),
[], [
'Warning' => [sprintf(
'Error %d in %s',
$exception->getCode(),
get_debug_type($middleware)
)]
],
sprintf( sprintf(
'Exception thrown in middleware %s: %s', 'Exception %d thrown in middleware %s: %s',
$exception->getCode(),
get_debug_type($middleware), get_debug_type($middleware),
$exception->getMessage() $exception->getMessage()
) )
@ -128,17 +133,13 @@ class QueueRequestHandler implements RequestHandler
/** /**
* Return the current response to the client. * Return the current response to the client.
* *
* @param ?int $exitCode Exit status after sending out the response or NULL to continue
*
* Must be in the range 0 to 254. The status 0 is used to terminate the program successfully.
*
* @return void * @return void
* *
* @throws RuntimeException if headers were already sent * @throws RuntimeException if headers were already sent
* *
* @api * @api
*/ */
public function respond(?int $exitCode = null): void public function respond(): void
{ {
$file = 'unknown file'; $file = 'unknown file';
$line = 0; $line = 0;
@ -166,17 +167,6 @@ class QueueRequestHandler implements RequestHandler
header($header, false); header($header, false);
} }
echo $this->response->getBody(); echo $this->response->getBody();
if (!is_null($exitCode)) {
$options = [
'options' => [
'default' => 1,
'min_range' => 0,
'max_range' => 254
]
];
$exitCode = filter_var($exitCode, FILTER_VALIDATE_INT, $options);
exit($exitCode);
}
} }
/** /**
@ -226,7 +216,7 @@ class QueueRequestHandler implements RequestHandler
{ {
$this->request = GuzzleRequest::fromGlobals(); $this->request = GuzzleRequest::fromGlobals();
$this->queue = MiddlewareQueue::getInstance($middlewares); $this->queue = MiddlewareQueue::getInstance($middlewares);
$this->response = new GuzzleResponse(200); $this->response = new GuzzleResponse();
} }
/** /**

55
doc/guides/changelog.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="changelog"> <section class="section " id="changelog">
<h1>Changelog</h1> <h1>Changelog</h1>
<div class="admonition-wrapper"> <div class="admonition-wrapper">
@ -158,6 +158,12 @@
<div class="contents"> <div class="contents">
<ul class="phpdocumentor-list"> <ul class="phpdocumentor-list">
<li class="toc-item"> <li class="toc-item">
<a href="guides/changelog.html#v1-2-0">v1.2.0</a>
</li>
<li class="toc-item">
<a href="guides/changelog.html#v1-1-0">v1.1.0</a> <a href="guides/changelog.html#v1-1-0">v1.1.0</a>
@ -181,7 +187,40 @@
</div> </div>
</div> </div>
<div class="section" id="v1-1-0"> <section class="section " id="v1-2-0">
<h2>v1.2.0</h2>
<p><strong>Minor Changes:</strong>
</p>
<ul>
<li>Added a <code>Warning</code>
header to identify response messages from converted exceptions</li>
<li>Removed the option to provide an exit status to <a href="classes/OCC-PSR15-QueueRequestHandler.html#method_respond"><abbr title="\OCC\PSR15\QueueRequestHandler::respond()">QueueRequestHandler::respond()</abbr></a>
</li>
<li>Added Composer command for development tools (PHP Mess Detector, Psalm Taint Analysis)</li>
</ul>
<p><strong>Maintencance:</strong>
</p>
<ul>
<li>Updated dependencies</li>
</ul>
</section>
<section class="section " id="v1-1-0">
<h2>v1.1.0</h2> <h2>v1.1.0</h2>
@ -217,9 +256,9 @@
</ul> </ul>
</div> </section>
<div class="section" id="v1-0-1"> <section class="section " id="v1-0-1">
<h2>v1.0.1</h2> <h2>v1.0.1</h2>
@ -233,18 +272,18 @@
</ul> </ul>
</div> </section>
<div class="section" id="v1-0-0"> <section class="section " id="v1-0-0">
<h2>v1.0.0</h2> <h2>v1.0.0</h2>
<p><strong>Initial Release</strong> <p><strong>Initial Release</strong>
</p> </p>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

10
doc/guides/index.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="documentation"> <section class="section " id="documentation">
<h1>Documentation</h1> <h1>Documentation</h1>
<div class="toc"> <div class="toc">
@ -209,6 +209,12 @@
<a href="guides/changelog.html#changelog">Changelog</a> <a href="guides/changelog.html#changelog">Changelog</a>
<ul class="section-level-1"> <ul class="section-level-1">
<li class="toc-item">
<a href="guides/changelog.html#v1-2-0">v1.2.0</a>
</li>
<li class="toc-item"> <li class="toc-item">
<a href="guides/changelog.html#v1-1-0">v1.1.0</a> <a href="guides/changelog.html#v1-1-0">v1.1.0</a>
@ -233,7 +239,7 @@
</ul> </ul>
</div> </div>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

32
doc/guides/overview/abstractmiddleware.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="abstractmiddleware"> <section class="section " id="abstractmiddleware">
<h1>AbstractMiddleware</h1> <h1>AbstractMiddleware</h1>
<div class="admonition-wrapper"> <div class="admonition-wrapper">
@ -197,11 +197,11 @@ both as needed.</p>
<p>The <code>AbstractMiddleware</code> <p>The <code>AbstractMiddleware</code>
implements the implements the <code>Psr\Http\Server\MiddlewareInterface</code>
<a href="https://www.php-fig.org/psr/psr-15/#22-psrhttpservermiddlewareinterface">Psr\Http\Server\MiddlewareInterface</a> following PHP-FIG&#039;s recommendation
following PHP-FIG&#039;s recommendation <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a>.</p> <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a>.</p>
<div class="section" id="properties"> <section class="section " id="properties">
<h2>Properties</h2> <h2>Properties</h2>
@ -211,9 +211,9 @@ following PHP-FIG&#039;s recommendation <a href="https://www.php-fig.org/psr/psr
handler which called the middleware. This can be used to access the request and/or response object (as properties of handler which called the middleware. This can be used to access the request and/or response object (as properties of
<a href="guides/overview/queuerequesthandler.html">QueueRequestHandler</a>) when they are otherwise not available.</p> <a href="guides/overview/queuerequesthandler.html">QueueRequestHandler</a>) when they are otherwise not available.</p>
</div> </section>
<div class="section" id="methods"> <section class="section " id="methods">
<h2>Methods</h2> <h2>Methods</h2>
@ -232,7 +232,7 @@ to receive a response, which is then processed by <a href="classes/OCC-PSR15-Abs
before before
returning it back to the request handler again.</p> returning it back to the request handler again.</p>
<div class="section" id="processing-a-request"> <section class="section " id="processing-a-request">
<h3>Processing a Request</h3> <h3>Processing a Request</h3>
@ -242,11 +242,12 @@ have to implement your own <code>processRequest()</code>
method. It takes a request object as only argument and must return a method. It takes a request object as only argument and must return a
valid request object as well. Just make sure it follows PHP-FIG&#039;s standard recommendation valid request object as well. Just make sure it follows PHP-FIG&#039;s standard recommendation
<a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the <a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the
<a href="https://www.php-fig.org/psr/psr-7/#321-psrhttpmessageserverrequestinterface">Psr\Http\Message\ServerRequestInterface</a>.</p> <code>Psr\Http\Message\ServerRequestInterface</code>
.</p>
</div> </section>
<div class="section" id="processing-a-response"> <section class="section " id="processing-a-response">
<h3>Processing a Response</h3> <h3>Processing a Response</h3>
@ -256,13 +257,14 @@ you have to implement your own <code>processResponse()</code>
method. It takes a response object as only argument and must return method. It takes a response object as only argument and must return
a valid response object as well. Just make sure it follows PHP-FIG&#039;s standard recommendation a valid response object as well. Just make sure it follows PHP-FIG&#039;s standard recommendation
<a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the <a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the
<a href="https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface">Psr\Http\Message\ResponseInterface</a>.</p> <code>Psr\Http\Message\ResponseInterface</code>
.</p>
</div> </section>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

4
doc/guides/overview/index.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="overview"> <section class="section " id="overview">
<h1>Overview</h1> <h1>Overview</h1>
@ -222,7 +222,7 @@ in other projects.</p>
</ul> </ul>
</div> </div>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

23
doc/guides/overview/middlewarequeue.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="middlewarequeue"> <section class="section " id="middlewarequeue">
<h1>MiddlewareQueue</h1> <h1>MiddlewareQueue</h1>
<div class="admonition-wrapper"> <div class="admonition-wrapper">
@ -187,7 +187,8 @@
manages the middlewares involved in processing a server request. It makes sure they are called in manages the middlewares involved in processing a server request. It makes sure they are called in
first-in, first-out (FIFO) order, i.e. the same order they were added to the queue. It also ensures all middlewares are first-in, first-out (FIFO) order, i.e. the same order they were added to the queue. It also ensures all middlewares are
implementing the <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a> specification for the implementing the <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a> specification for the
<a href="https://www.php-fig.org/psr/psr-15/#22-psrhttpservermiddlewareinterface">Psr\Http\Server\MiddlewareInterface</a>.</p> <code>Psr\Http\Server\MiddlewareInterface</code>
.</p>
<p>When instantiating a <code>MiddlewareQueue</code> <p>When instantiating a <code>MiddlewareQueue</code>
@ -215,10 +216,10 @@ $queue-&gt;enqueue(new MiddlewareTwo());</code></pre>
<p>The <code>MiddlewareQueue</code> <p>The <code>MiddlewareQueue</code>
is based on a is based on a <code>OCC\Basics\DataStructures\StrictQueue</code>
<a href="https://opencultureconsulting.github.io/php-basics/guides/overview/datastructures.html#strictqueue">OCC\Basics\DataStructures\StrictQueue</a>.</p> .</p>
<div class="section" id="methods"> <section class="section " id="methods">
<h2>Methods</h2> <h2>Methods</h2>
@ -233,7 +234,7 @@ returns the first item from the queue.</p>
<p>For a complete API documentation have a look at the <p>For a complete API documentation have a look at the
<a href="https://opencultureconsulting.github.io/php-basics/classes/OCC-Basics-DataStructures-StrictQueue.html">StrictQueue</a>.</p> <a href="https://opencultureconsulting.github.io/php-basics/classes/OCC-Basics-DataStructures-StrictQueue.html">StrictQueue</a>.</p>
<div class="section" id="adding-a-middleware"> <section class="section " id="adding-a-middleware">
<h3>Adding a Middleware</h3> <h3>Adding a Middleware</h3>
@ -247,9 +248,9 @@ criterion an <code>OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException
<p>Have a look at the <a href="guides/overview/abstractmiddleware.html">AbstractMiddleware</a> for an easy way to create your own middlewares!</p> <p>Have a look at the <a href="guides/overview/abstractmiddleware.html">AbstractMiddleware</a> for an easy way to create your own middlewares!</p>
</div> </section>
<div class="section" id="fetching-the-next-in-line"> <section class="section " id="fetching-the-next-in-line">
<h3>Fetching the next in line</h3> <h3>Fetching the next in line</h3>
@ -263,11 +264,11 @@ Also, this middleware is removed from the queue.</p>
) )
before trying to dequeue an item!</p> before trying to dequeue an item!</p>
</div> </section>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

56
doc/guides/overview/queuerequesthandler.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="queuerequesthandler"> <section class="section " id="queuerequesthandler">
<h1>QueueRequestHandler</h1> <h1>QueueRequestHandler</h1>
<div class="admonition-wrapper"> <div class="admonition-wrapper">
@ -215,14 +215,14 @@ a middleware and turns them into a proper HTTP error response.</p>
<p>The <code>QueueRequestHandler</code> <p>The <code>QueueRequestHandler</code>
implements the implements the <code>Psr\Http\Server\RequestHandlerInterface</code>
<a href="https://www.php-fig.org/psr/psr-15/#21-psrhttpserverrequesthandlerinterface">Psr\Http\Server\RequestHandlerInterface</a> following PHP-FIG&#039;s recommendation
following PHP-FIG&#039;s recommendation <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a>.</p> <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a>.</p>
<p>For a minimal working example have a look at <a href="guides/usage/usage.html">Usage</a>.</p> <p>For a minimal working example have a look at <a href="guides/usage/usage.html">Usage</a>.</p>
<div class="section" id="properties"> <section class="section " id="properties">
<h2>Properties</h2> <h2>Properties</h2>
@ -232,7 +232,7 @@ following PHP-FIG&#039;s recommendation <a href="https://www.php-fig.org/psr/psr
directly accessed from the object via magic methods (e.g. <code>$requestHandler-&gt;queue</code> directly accessed from the object via magic methods (e.g. <code>$requestHandler-&gt;queue</code>
).</p> ).</p>
<div class="section" id="middleware-queue"> <section class="section " id="middleware-queue">
<h3>Middleware Queue</h3> <h3>Middleware Queue</h3>
@ -268,16 +268,17 @@ $requestHandler-&gt;queue-&gt;enqueue(new MiddlewareOne());
$requestHandler-&gt;queue-&gt;enqueue(new MiddlewareTwo());</code></pre> $requestHandler-&gt;queue-&gt;enqueue(new MiddlewareTwo());</code></pre>
</blockquote> </blockquote>
</div> </section>
<div class="section" id="http-server-request"> <section class="section " id="http-server-request">
<h3>HTTP Server Request</h3> <h3>HTTP Server Request</h3>
<p>The server request is always available as <code>QueueRequestHandler::request</code> <p>The server request is always available as <code>QueueRequestHandler::request</code>
. It follows PHP-FIG&#039;s standard recommendation . It follows PHP-FIG&#039;s standard recommendation
<a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the <a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the
<a href="https://www.php-fig.org/psr/psr-7/#321-psrhttpmessageserverrequestinterface">Psr\Http\Message\ServerRequestInterface</a>.</p> <code>Psr\Http\Message\ServerRequestInterface</code>
.</p>
<p>When instantiating a <code>QueueRequestHandler</code> <p>When instantiating a <code>QueueRequestHandler</code>
@ -286,16 +287,17 @@ $requestHandler-&gt;queue-&gt;enqueue(new MiddlewareTwo());</code></pre>
request data from superglobals. The property is reset each time the request is passed through a middleware and thus request data from superglobals. The property is reset each time the request is passed through a middleware and thus
always represents the current state of the request.</p> always represents the current state of the request.</p>
</div> </section>
<div class="section" id="http-response"> <section class="section " id="http-response">
<h3>HTTP Response</h3> <h3>HTTP Response</h3>
<p>The response can be read as <code>QueueRequestHandler::response</code> <p>The response can be read as <code>QueueRequestHandler::response</code>
. It also follows PHP-FIG&#039;s standard recommendation . It also follows PHP-FIG&#039;s standard recommendation
<a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the <a href="https://www.php-fig.org/psr/psr-7/">PSR-7: HTTP Message Interfaces</a> and implements the
<a href="https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface">Psr\Http\Message\ResponseInterface</a>.</p> <code>Psr\Http\Message\ResponseInterface</code>
.</p>
<p>When instantiating a <code>QueueRequestHandler</code> <p>When instantiating a <code>QueueRequestHandler</code>
@ -308,11 +310,11 @@ always represents the latest state of the response.</p>
<p>Both, request and response, use the awesome implementations of <a href="https://github.com/guzzle/psr7">Guzzle</a>.</p> <p>Both, request and response, use the awesome implementations of <a href="https://github.com/guzzle/psr7">Guzzle</a>.</p>
</div> </section>
</div> </section>
<div class="section" id="methods"> <section class="section " id="methods">
<h2>Methods</h2> <h2>Methods</h2>
@ -325,7 +327,7 @@ while the latter sends the response back to the client. Invoking the request han
calling the <code>handle()</code> calling the <code>handle()</code>
method.</p> method.</p>
<div class="section" id="handling-a-server-request"> <section class="section " id="handling-a-server-request">
<h3>Handling a Server Request</h3> <h3>Handling a Server Request</h3>
@ -346,28 +348,24 @@ implements <code>Psr\Http\Message\ResponseInterface</code>
<p>In case of an error the request handler catches any exception and creates a response with the exception code as status <p>In case of an error the request handler catches any exception and creates a response with the exception code as status
code (if it&#039;s within the valid range of HTTP status codes, otherwise it&#039;s set to <code>500 (Internal Server Error)</code> code (if it&#039;s within the valid range of HTTP status codes, otherwise it&#039;s set to <code>500 (Internal Server Error)</code>
), and ), and
the exception message as body.</p> the exception message as body. Such a response can be identified by having a <code>Warning</code>
header set including the error
code and the affected middleware.</p>
</div> </section>
<div class="section" id="sending-the-response"> <section class="section " id="sending-the-response">
<h3>Sending the Response</h3> <h3>Sending the Response</h3>
<p>Sending the final response to the client is as easy as calling <a href="classes/OCC-PSR15-QueueRequestHandler.html#method_respond"><abbr title="\OCC\PSR15\QueueRequestHandler::respond()">QueueRequestHandler::respond()</abbr></a> <p>Sending the final response to the client is as easy as calling <a href="classes/OCC-PSR15-QueueRequestHandler.html#method_respond"><abbr title="\OCC\PSR15\QueueRequestHandler::respond()">QueueRequestHandler::respond()</abbr></a>
. .</p>
Optionally, you can provide an exit code as argument (an integer in the range <code>0</code>
to <code>254</code>
). If you do so, script
execution is stopped after sending out the response and the given exit status is set. The status <code>0</code>
means the request
was handled successfully, every other status is considered an error.</p>
</div> </section>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

4
doc/guides/usage/index.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="user-guide"> <section class="section " id="user-guide">
<h1>User Guide</h1> <h1>User Guide</h1>
@ -233,7 +233,7 @@ application. For a detailed description of the package&#039;s contents have a lo
</ul> </ul>
</div> </div>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

16
doc/guides/usage/installation.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="installation"> <section class="section " id="installation">
<h1>Installation</h1> <h1>Installation</h1>
<div class="admonition-wrapper"> <div class="admonition-wrapper">
@ -181,7 +181,7 @@
</div> </div>
</div> </div>
<div class="section" id="composer"> <section class="section " id="composer">
<h2>Composer</h2> <h2>Composer</h2>
@ -203,9 +203,9 @@ composer require &quot;opencultureconsulting/psr15:~1.1&quot;</code></pre>
<p>All available versions as well as further information about <a href="guides/usage/requirements.html">Requirements</a> and dependencies can be found on <p>All available versions as well as further information about <a href="guides/usage/requirements.html">Requirements</a> and dependencies can be found on
<a href="https://packagist.org/packages/opencultureconsulting/psr15">Packagist</a>.</p> <a href="https://packagist.org/packages/opencultureconsulting/psr15">Packagist</a>.</p>
</div> </section>
<div class="section" id="git"> <section class="section " id="git">
<h2>Git</h2> <h2>Git</h2>
@ -227,18 +227,18 @@ git clone --branch=v1.1.0 https://github.com/opencultureconsulting/psr-15.git ps
<p>Be aware that you also need to make the classes available in your application by either adding them to your autoloader <p>Be aware that you also need to make the classes available in your application by either adding them to your autoloader
or by including all files individually in PHP. Also don&#039;t forget to do the same for all <a href="guides/usage/requirements.html">Requirements</a>.</p> or by including all files individually in PHP. Also don&#039;t forget to do the same for all <a href="guides/usage/requirements.html">Requirements</a>.</p>
</div> </section>
<div class="section" id="download"> <section class="section " id="download">
<h2>Download</h2> <h2>Download</h2>
<p>As a last resort you can also just download the files. You can find all available versions as well as the current <p>As a last resort you can also just download the files. You can find all available versions as well as the current
development state on the <a href="https://github.com/opencultureconsulting/psr-15/releases">GitHub release page</a>.</p> development state on the <a href="https://github.com/opencultureconsulting/psr-15/releases">GitHub release page</a>.</p>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

12
doc/guides/usage/requirements.html
View File

@ -150,10 +150,10 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="requirements"> <section class="section " id="requirements">
<h1>Requirements</h1> <h1>Requirements</h1>
<div class="section" id="environment"> <section class="section " id="environment">
<h2>Environment</h2> <h2>Environment</h2>
@ -165,9 +165,9 @@
although it is technically not strictly required for using any of these classes. But it certainly makes it a lot although it is technically not strictly required for using any of these classes. But it certainly makes it a lot
easier!</p> easier!</p>
</div> </section>
<div class="section" id="dependencies"> <section class="section " id="dependencies">
<h2>Dependencies</h2> <h2>Dependencies</h2>
@ -184,9 +184,9 @@ of the great <a href="https://packagist.org/packages/guzzlehttp/psr7">guzzlehttp
of the <a href="https://packagist.org/packages/opencultureconsulting/basics">opencultureconsulting/basics</a> package which also of the <a href="https://packagist.org/packages/opencultureconsulting/basics">opencultureconsulting/basics</a> package which also
provides some useful traits.</p> provides some useful traits.</p>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

16
doc/guides/usage/usage.html
View File

@ -150,7 +150,7 @@
</aside> </aside>
<div class="phpdocumentor-column -nine phpdocumentor-content"> <div class="phpdocumentor-column -nine phpdocumentor-content">
<div class="section" id="usage"> <section class="section " id="usage">
<h1>Usage</h1> <h1>Usage</h1>
<div class="admonition-wrapper"> <div class="admonition-wrapper">
@ -188,7 +188,7 @@
and <code>MiddlewareTwo</code> and <code>MiddlewareTwo</code>
).</p> ).</p>
<div class="section" id="middlewares"> <section class="section " id="middlewares">
<h2>Middlewares</h2> <h2>Middlewares</h2>
@ -304,9 +304,9 @@ class MiddlewareTwo extends AbstractMiddleware
<p>Well done! We now have two middlewares.</p> <p>Well done! We now have two middlewares.</p>
</div> </section>
<div class="section" id="request-handler"> <section class="section " id="request-handler">
<h2>Request Handler</h2> <h2>Request Handler</h2>
@ -341,9 +341,9 @@ $requestHandler-&gt;respond();
<p>And that&#039;s it!</p> <p>And that&#039;s it!</p>
</div> </section>
<div class="section" id="diving-deeper"> <section class="section " id="diving-deeper">
<h2>Diving Deeper</h2> <h2>Diving Deeper</h2>
@ -365,9 +365,9 @@ is not <code>MiddlewareTwo</code>
response status code to <code>500</code> response status code to <code>500</code>
.</p> .</p>
</div> </section>
</div> </section>
</div> </div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden"> <section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">

8
doc/index.html generated
View File

@ -167,9 +167,11 @@
your own middleware, but you can just as well use any middleware that implements the middleware interface specified your own middleware, but you can just as well use any middleware that implements the middleware interface specified
by PSR-15 (e.g. from the awesome <a href="https://github.com/middlewares">PSR-15 HTTP Middlewares</a> project).</p> by PSR-15 (e.g. from the awesome <a href="https://github.com/middlewares">PSR-15 HTTP Middlewares</a> project).</p>
<p>All components of this package follow the highest coding standards of <a href="https://phpstan.org/">PHPStan</a> <p>All components of this package follow the highest coding standards of <a href="https://psalm.dev/">Psalm</a>,
and <a href="https://psalm.dev/">Psalm</a>, and comply to <a href="https://www.php-fig.org/psr/psr-12/">PSR-12</a> <a href="https://phpstan.org/">PHPStan</a>, <a href="https://phpmd.org/">PHP Mess Detector</a>,
code style guidelines to make sure they can be combined and easily re-used in other projects.</p> <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer/">PHP_CodeSniffer</a>, and comply to
<a href="https://www.php-fig.org/psr/psr-12/">PSR-12</a> code style guidelines to make sure they can be combined
and easily re-used in other projects.</p>
<h3 id="toc">Table of Contents</h3> <h3 id="toc">Table of Contents</h3>