psr-15/doc/guides/overview/middlewarequeue.html

298 lines
12 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="middlewarequeue">
<h1>MiddlewareQueue</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/overview/middlewarequeue.html#methods">Methods</a>
<ul class="section-level-2">
<li class="toc-item">
<a href="guides/overview/middlewarequeue.html#adding-a-middleware">Adding a Middleware</a>
</li>
<li class="toc-item">
<a href="guides/overview/middlewarequeue.html#fetching-the-next-in-line">Fetching the next in line</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<p>The <code>MiddlewareQueue</code>
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
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>
<p>When instantiating a <code>MiddlewareQueue</code>
it defaults to being empty. But you can optionally pass an iterable set of
middlewares to the constructor which are then put into the queue. To demonstrate, the following examples both have
exactly the same result.</p>
<blockquote>
<p>Examples:</p>
<pre><code class="language-php">use OCC\PSR15\MiddlewareQueue;
$middlewares = [
new MiddlewareOne(),
new MiddlewareTwo()
];
$queue = new MiddlewareQueue($middlewares);</code></pre>
<pre><code class="language-php">use OCC\PSR15\MiddlewareQueue;
$queue = new MiddlewareQueue();
$queue-&gt;enqueue(new MiddlewareOne());
$queue-&gt;enqueue(new MiddlewareTwo());</code></pre>
</blockquote>
<p>The <code>MiddlewareQueue</code>
is based on a
<a href="https://opencultureconsulting.github.io/php-basics/guides/overview/datastructures.html#strictqueue">OCC\Basics\DataStructures\StrictQueue</a>.</p>
<div class="section" id="methods">
<h2>Methods</h2>
<p>The <code>MiddlewareQueue</code>
provides a set of API methods, with <code>MiddlewareQueue::enqueue()</code>
and <code>MiddlewareQueue::dequeue()</code>
being the most relevant ones. The former will add a new item at the end of the queue while the latter removes and
returns the first item from the queue.</p>
<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>
<div class="section" id="adding-a-middleware">
<h3>Adding a Middleware</h3>
<p>Invoking <code>MiddlewareQueue::enqueue()</code>
will add a middleware at the end of the queue. The only argument must be a
middleware object implementing the <code>Psr\Http\Server\MiddlewareInterface</code>
. If the given argument does not meet the
criterion an <code>OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException</code>
is thrown.</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>
<div class="section" id="fetching-the-next-in-line">
<h3>Fetching the next in line</h3>
<p>Calling <code>MiddlewareQueue::dequeue()</code>
will return the first middleware from the queue, i.e. the oldest one on the queue.
Also, this middleware is removed from the queue.</p>
<p>If the queue is empty a <code>RuntimeException</code>
is thrown, so make sure to check the queue&#039;s length (e.g. with <code>count()</code>
)
before trying to dequeue an item!</p>
</div>
</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>