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

398 lines
17 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>PSR-15 Queue</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<base href="../../">
<link rel="icon" href="images/favicon.ico"/>
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/base.css">
<link rel="preconnect" href="https://fonts.gstatic.com">
<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@100;200;300;400;600;700&display=swap" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Source+Code+Pro:wght@400;600;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="css/template.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0/css/all.min.css" integrity="sha256-ybRkN9dBjhcS2qrW1z+hfCxq+1aBdwyQM5wlQoQVt/0=" crossorigin="anonymous" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/themes/prism-okaidia.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/line-numbers/prism-line-numbers.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/line-highlight/prism-line-highlight.css">
<script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script>
<script src="https://cdn.jsdelivr.net/npm/css-vars-ponyfill@2"></script>
<script src="js/template.js"></script>
<script src="js/search.js"></script>
<script defer src="js/searchIndex.js"></script>
</head>
<body id="top">
<header class="phpdocumentor-header phpdocumentor-section">
<h1 class="phpdocumentor-title"><a href="" class="phpdocumentor-title__link">PSR-15 Queue</a></h1>
<input class="phpdocumentor-header__menu-button" type="checkbox" id="menu-button" name="menu-button" />
<label class="phpdocumentor-header__menu-icon" for="menu-button">
<i class="fas fa-bars"></i>
</label>
<section data-search-form class="phpdocumentor-search">
<label>
<span class="visually-hidden">Search for</span>
<svg class="phpdocumentor-search__icon" width="21" height="20" viewBox="0 0 21 20" fill="none" xmlns="http://www.w3.org/2000/svg">
<circle cx="7.5" cy="7.5" r="6.5" stroke="currentColor" stroke-width="2"/>
<line x1="12.4892" y1="12.2727" x2="19.1559" y2="18.9393" stroke="currentColor" stroke-width="3"/>
</svg>
<input type="search" class="phpdocumentor-field phpdocumentor-search__field" placeholder="Loading .." disabled />
</label>
</section>
<nav class="phpdocumentor-topnav">
<ul class="phpdocumentor-topnav__menu">
<li class="phpdocumentor-topnav__menu-item -menu">
<a href="https://packagist.org/packages/opencultureconsulting/basics">
<span>
<i class="fab fa-php"></i>
</span>
</a>
</li>
<li class="phpdocumentor-topnav__menu-item -menu">
<a href="https://github.com/opencultureconsulting/php-basics">
<span>
<i class="fab fa-github"></i>
</span>
</a>
</li>
</ul>
</nav>
</header>
<main class="phpdocumentor">
<div class="phpdocumentor-section">
<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" />
<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
Menu
</label>
<aside class="phpdocumentor-column -three phpdocumentor-sidebar">
<section class="phpdocumentor-sidebar__category -documentation">
<h2 class="phpdocumentor-sidebar__category-header">Documentation</h2>
<h4 class="phpdocumentor-sidebar__root-namespace">
<a href="guides/overview/index.html#overview" class="">Overview</a>
</h4>
<ul class="phpdocumentor-list">
<li>
<a href="guides/overview/queuerequesthandler.html#queuerequesthandler" class="">QueueRequestHandler</a>
</li>
<li>
<a href="guides/overview/middlewarequeue.html#middlewarequeue" class="">MiddlewareQueue</a>
</li>
<li>
<a href="guides/overview/abstractmiddleware.html#abstractmiddleware" class="">AbstractMiddleware</a>
</li>
</ul>
<h4 class="phpdocumentor-sidebar__root-namespace">
<a href="guides/usage/index.html#user-guide" class="">User Guide</a>
</h4>
<ul class="phpdocumentor-list">
<li>
<a href="guides/usage/requirements.html#requirements" class="">Requirements</a>
</li>
<li>
<a href="guides/usage/installation.html#installation" class="">Installation</a>
</li>
<li>
<a href="guides/usage/usage.html#usage" class="">Usage</a>
</li>
</ul>
<h4 class="phpdocumentor-sidebar__root-namespace">
<a href="guides/changelog.html#changelog" class="">Changelog</a>
</h4>
</section>
<section class="phpdocumentor-sidebar__category -namespaces">
<h2 class="phpdocumentor-sidebar__category-header">Namespaces</h2>
<h4 class="phpdocumentor-sidebar__root-namespace">
<a href="namespaces/occ.html" class="">OCC</a>
</h4>
<ul class="phpdocumentor-list">
<li>
<a href="namespaces/occ-psr15.html" class="">PSR15</a>
</li>
</ul>
</section>
<section class="phpdocumentor-sidebar__category -packages">
<h2 class="phpdocumentor-sidebar__category-header">Packages</h2>
<h4 class="phpdocumentor-sidebar__root-namespace">
<a href="packages/PSR15.html" class="">PSR15</a>
</h4>
</section>
<section class="phpdocumentor-sidebar__category -reports">
<h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/deprecated.html">Deprecated</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/errors.html">Errors</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
</section>
<section class="phpdocumentor-sidebar__category -indices">
<h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
</section>
</aside>
<div class="phpdocumentor-column -nine phpdocumentor-content">
<section class="section " id="usage">
<h1>Usage</h1>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">Table of Contents</p>
<div class="contents">
<ul class="phpdocumentor-list">
<li class="toc-item">
<a href="guides/usage/usage.html#middlewares">Middlewares</a>
</li>
<li class="toc-item">
<a href="guides/usage/usage.html#request-handler">Request Handler</a>
</li>
<li class="toc-item">
<a href="guides/usage/usage.html#diving-deeper">Diving Deeper</a>
</li>
</ul>
</div>
</div>
</div>
<p>The following example shows a very basic <em>Queue-based HTTP Server Request Handler</em>
using just two simple middlewares
(called <code>MiddlewareOne</code>
and <code>MiddlewareTwo</code>
).</p>
<section class="section " id="middlewares">
<h2>Middlewares</h2>
<p>First of all, we need some middlewares to process our server request. Although we could use any middleware implementing
the <code>Psr/Http/Server/MiddlewareInterface</code>
(e.g. from <a href="https://github.com/middlewares">this great collection</a>), we
will write our own using the <a href="guides/overview/abstractmiddleware.html">AbstractMiddleware</a> provided by this package.</p>
<p>The abstract middleware already implements a complete middleware, but it will just pass requests through without doing
anything. In order to have it do something, we need to implement our own <a href="classes/OCC-PSR15-AbstractMiddleware.html#method_processRequest"><abbr title="\OCC\PSR15\AbstractMiddleware::processRequest()">AbstractMiddleware::processRequest()</abbr></a>
or <a href="classes/OCC-PSR15-AbstractMiddleware.html#method_processResponse"><abbr title="\OCC\PSR15\AbstractMiddleware::processResponse()">AbstractMiddleware::processResponse()</abbr></a>
method, or both of them.</p>
<p>The logic here is the same as with every <a href="https://www.php-fig.org/psr/psr-15/">PSR-15: HTTP Server Request Handlers</a>
middleware: The request gets passed through all middlewares&#039; <code>processRequest()</code>
methods in order of their addition to
the queue, then a response is created and passed through all <code>processResponse()</code>
methods, <strong>but in reverse order</strong>
! So
the first middleware in the queue gets the request first, but the response last.</p>
<p>Our first middleware is very simple and just adds an attribute to the server request.</p>
<pre><code class="language-php">use OCC\PSR15\AbstractMiddleware;
use Psr\Http\Message\ServerRequestInterface as ServerRequest;
class MiddlewareOne extends AbstractMiddleware
{
/**
* Process an incoming server request before delegating to next middleware.
*
* @param ServerRequest $request The incoming server request
*
* @return ServerRequest The processed server request
*/
protected function processRequest(ServerRequest $request): ServerRequest
{
// Let&#039;s just add a new attribute to the request to later check
// which middleware was passed last.
return $request-&gt;withAttribute(&#039;LastMiddlewarePassed&#039;, &#039;MiddlewareOne&#039;);
}
}</code></pre>
<p>For a queue to make sense we need at least a second middleware, so let&#039;s create another one. Again, we will add an
attribute to the request, but with the same name. So, whichever middleware handles the request last overwrites the
attribute with its value. This way we can later check if our middlewares were passed in the correct order.</p>
<pre><code class="language-php">use OCC\PSR15\AbstractMiddleware;
use Psr\Http\Message\ServerRequestInterface as ServerRequest;
class MiddlewareTwo extends AbstractMiddleware
{
/**
* Process an incoming server request before delegating to next middleware.
*
* @param ServerRequest $request The incoming server request
*
* @return ServerRequest The processed server request
*/
protected function processRequest(ServerRequest $request): ServerRequest
{
// We add the same request attribute as in MiddlewareOne, effectively
// overwriting its value.
return $request-&gt;withAttribute(&#039;LastMiddlewarePassed&#039;, &#039;MiddlewareTwo&#039;);
}
}</code></pre>
<p>Also, we want to set the status code of the response according to the final value of our request attribute. Therefore,
we need to implement <code>processResponse()</code>
as well. We can do that in either one of our middlewares because it&#039;s the only
response manipulation in our example, so the order of processing doesn&#039;t make a difference (remember: <code>MiddlewareTwo</code>
gets to handle the response before <code>MiddlewareOne</code>
). Let&#039;s go with <code>MiddlewareTwo</code>
.</p>
<pre><code class="language-php">use OCC\PSR15\AbstractMiddleware;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as ServerRequest;
class MiddlewareTwo extends AbstractMiddleware
{
// MiddlewareTwo::processRequest() remains unchanged (see above).
/**
* Process an incoming response before returning it to previous middleware.
*
* @param Response $response The incoming response
*
* @return Response The processed response
*/
protected function processResponse(Response $response): Response
{
// First we need to get the request attribute.
$lastMiddlewarePassed = $this-&gt;requestHandler-&gt;request-&gt;getAttribute(&#039;LastMiddlewarePassed&#039;);
if ($lastMiddlewarePassed === &#039;MiddlewareTwo&#039;) {
// Great, MiddlewareTwo was passed after MiddlewareOne,
// let&#039;s return status code 200!
return $response-&gt;withStatus(200);
} else {
// Oh no, something went wrong! We&#039;ll send status code 500.
return $response-&gt;withStatus(500);
}
}
}</code></pre>
<p>Well done! We now have two middlewares.</p>
</section>
<section class="section " id="request-handler">
<h2>Request Handler</h2>
<p>Let&#039;s use a <a href="guides/overview/queuerequesthandler.html">QueueRequestHandler</a> to pass a server request through both of our middlewares in the
correct order.</p>
<pre><code class="language-php">use OCC\PSR15\QueueRequestHandler;
// First of all, we instantiate the request handler.
// At this point we could already provide an array of middlewares as argument and
// skip the next step, but then we wouldn&#039;t learn how to use the MiddlewareQueue.
$requestHandler = new QueueRequestHandler();
// We can access the MiddlewareQueue as a property of the request handler.
// Let&#039;s add both of our middlewares, MiddlewareOne and MiddlewareTwo. Since
// this is a FIFO queue, the order is very important!
$requestHandler-&gt;queue-&gt;enqueue(new MiddlewareOne());
$requestHandler-&gt;queue-&gt;enqueue(new MiddlewareTwo());
// And we are ready to handle incoming requests!
// We don&#039;t even need to pass the server request to this method, because
// the constructor already took care of that!
$finalResponse = $requestHandler-&gt;handle();
// Now we can pass the final response back to our application.
// Alternatively, we can also return it directly to the client.
$requestHandler-&gt;respond();
// If we did everything right, the client should now receive an HTTP response
// with status code 200 (OK).</code></pre>
<p>And that&#039;s it!</p>
</section>
<section class="section " id="diving-deeper">
<h2>Diving Deeper</h2>
<p>To familiarize yourself with the FIFO principle of the middleware queue, you can try to exchange the two lines adding
the middlewares to the queue, i.e. add <code>MiddlewareTwo</code>
first and <code>MiddlewareOne</code>
second. This will result in an HTTP
response with status code <code>500 (Internal Server Error)</code>
.</p>
<p>This is exactly what we intended: Have a look at <code>MiddlewareTwo::processResponse()</code>
again! If <code>$lastMiddlewarePassed</code>
is not <code>MiddlewareTwo</code>
(which it isn&#039;t when <code>MiddlewareOne</code>
is added to the queue after <code>MiddlewareTwo</code>
), we set the
response status code to <code>500</code>
.</p>
</section>
</section>
</div>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">
<section class="phpdocumentor-search-results__dialog">
<header class="phpdocumentor-search-results__header">
<h2 class="phpdocumentor-search-results__title">Search results</h2>
<button class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
</header>
<section class="phpdocumentor-search-results__body">
<ul class="phpdocumentor-search-results__entries"></ul>
</section>
</section>
</section>
</div>
<a href="#top" class="phpdocumentor-back-to-top"><i class="fas fa-chevron-circle-up"></i></a>
</main>
<script>
cssVars({});
</script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/prism.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/autoloader/prism-autoloader.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/line-numbers/prism-line-numbers.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.23.0/plugins/line-highlight/prism-line-highlight.min.js"></script>
</body>
</html>
View Git Blame Copy Permalink