398 lines
17 KiB
HTML
398 lines
17 KiB
HTML
|
<!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">
|
||
|
|
<div 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>
|
||
|
|
|
||
|
|
<div 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 Handler</a>
|
||
|
|
middleware: The request gets passed through all middlewares' <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's just add a new attribute to the request to later check
|
||
|
|
// which middleware was passed last.
|
||
|
|
return $request->withAttribute('LastMiddlewarePassed', 'MiddlewareOne');
|
||
|
|
}
|
||
|
|
}</code></pre>
|
||
|
|
|
||
|
|
|
||
|
|
<p>For a queue to make sense we need at least a second middleware, so let'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->withAttribute('LastMiddlewarePassed', 'MiddlewareTwo');
|
||
|
|
}
|
||
|
|
}</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's the only
|
||
|
|
response manipulation in our example, so the order of processing doesn't make a difference (remember: <code>MiddlewareTwo</code>
|
||
|
|
|
||
|
|
gets to handle the response before <code>MiddlewareOne</code>
|
||
|
|
). Let'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->requestHandler->request->getAttribute('LastMiddlewarePassed');
|
||
|
|
if ($lastMiddlewarePassed === 'MiddlewareTwo') {
|
||
|
|
// Great, MiddlewareTwo was passed after MiddlewareOne,
|
||
|
|
// let's return status code 200!
|
||
|
|
return $response->withStatus(200);
|
||
|
|
} else {
|
||
|
|
// Oh no, something went wrong! We'll send status code 500.
|
||
|
|
return $response->withStatus(500);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}</code></pre>
|
||
|
|
|
||
|
|
|
||
|
|
<p>Well done! We now have two middlewares.</p>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="section" id="request-handler">
|
||
|
|
<h2>Request Handler</h2>
|
||
|
|
|
||
|
|
|
||
|
|
<p>Let'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't learn how to use the MiddlewareQueue.
|
||
|
|
$requestHandler = new QueueRequestHandler();
|
||
|
|
|
||
|
|
// We can access the MiddlewareQueue as a property of the request handler.
|
||
|
|
// Let's add both of our middlewares, MiddlewareOne and MiddlewareTwo. Since
|
||
|
|
// this is a FIFO queue, the order is very important!
|
||
|
|
$requestHandler->queue->enqueue(new MiddlewareOne());
|
||
|
|
$requestHandler->queue->enqueue(new MiddlewareTwo());
|
||
|
|
|
||
|
|
// And we are ready to handle incoming requests!
|
||
|
|
// We don't even need to pass the server request to this method, because
|
||
|
|
// the constructor already took care of that!
|
||
|
|
$finalResponse = $requestHandler->handle();
|
||
|
|
|
||
|
|
// Now we can pass the final response back to our application.
|
||
|
|
// Alternatively, we can also return it directly to the client.
|
||
|
|
$requestHandler->respond();
|
||
|
|
|
||
|
|
// If we did everything right, the client should now receive an HTTP response
|
||
|
|
// with status code 200 (OK).</code></pre>
|
||
|
|
|
||
|
|
|
||
|
|
<p>And that's it!</p>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div 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. adding <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'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>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</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>
|