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="queuerequesthandler">
|
|
<h1>QueueRequestHandler</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/queuerequesthandler.html#properties">Properties</a>
|
|
|
|
<ul class="section-level-2">
|
|
<li class="toc-item">
|
|
<a href="guides/overview/queuerequesthandler.html#middleware-queue">Middleware Queue</a>
|
|
|
|
|
|
</li>
|
|
|
|
<li class="toc-item">
|
|
<a href="guides/overview/queuerequesthandler.html#http-server-request">HTTP Server Request</a>
|
|
|
|
|
|
</li>
|
|
|
|
<li class="toc-item">
|
|
<a href="guides/overview/queuerequesthandler.html#http-response">HTTP Response</a>
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="toc-item">
|
|
<a href="guides/overview/queuerequesthandler.html#methods">Methods</a>
|
|
|
|
<ul class="section-level-2">
|
|
<li class="toc-item">
|
|
<a href="guides/overview/queuerequesthandler.html#handling-a-server-request">Handling a Server Request</a>
|
|
|
|
|
|
</li>
|
|
|
|
<li class="toc-item">
|
|
<a href="guides/overview/queuerequesthandler.html#sending-the-response">Sending the Response</a>
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<p>The <code>QueueRequestHandler</code>
|
|
is the core piece of this package. It fetches incoming HTTP requests, passes them through a
|
|
queue of middlewares and finally sends the response back to the client. It also catches any exceptions not handled by
|
|
a middleware and turns them into a proper HTTP error response.</p>
|
|
|
|
|
|
<p>The <code>QueueRequestHandler</code>
|
|
implements the
|
|
<a href="https://www.php-fig.org/psr/psr-15/#21-psrhttpserverrequesthandlerinterface">Psr\Http\Server\RequestHandlerInterface</a>
|
|
following PHP-FIG's recommendation <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>
|
|
|
|
<div class="section" id="properties">
|
|
<h2>Properties</h2>
|
|
|
|
|
|
<p>The <code>QueueRequestHandler</code>
|
|
has three <strong>read-only</strong>
|
|
properties. They are initially set at instantiation and can be
|
|
directly accessed from the object via magic methods (e.g. <code>$requestHandler->queue</code>
|
|
).</p>
|
|
|
|
<div class="section" id="middleware-queue">
|
|
<h3>Middleware Queue</h3>
|
|
|
|
|
|
<p>The queue of middlewares can be accessed as <code>QueueRequestHandler::queue</code>
|
|
and offers a handy API to <code>enqueue()</code>
|
|
,
|
|
<code>dequeue()</code>
|
|
or otherwise manipulate its contents. All middlewares must implement <code>Psr\Http\Server\MiddlewareInterface</code>
|
|
.
|
|
Have a look at <a href="guides/overview/middlewarequeue.html">MiddlewareQueue</a> for more details.</p>
|
|
|
|
|
|
<p>When instantiating a <code>QueueRequestHandler</code>
|
|
the queue 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\QueueRequestHandler;
|
|
|
|
$middlewares = [
|
|
new MiddlewareOne(),
|
|
new MiddlewareTwo()
|
|
];
|
|
|
|
$requestHandler = new QueueRequestHandler($middlewares);</code></pre>
|
|
<pre><code class="language-php">use OCC\PSR15\QueueRequestHandler;
|
|
|
|
$requestHandler = new QueueRequestHandler();
|
|
|
|
$requestHandler->queue->enqueue(new MiddlewareOne());
|
|
$requestHandler->queue->enqueue(new MiddlewareTwo());</code></pre>
|
|
</blockquote>
|
|
|
|
</div>
|
|
|
|
<div class="section" id="http-server-request">
|
|
<h3>HTTP Server Request</h3>
|
|
|
|
|
|
<p>The server request is always available as <code>QueueRequestHandler::request</code>
|
|
. It follows PHP-FIG'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/#321-psrhttpmessageserverrequestinterface">Psr\Http\Message\ServerRequestInterface</a>.</p>
|
|
|
|
|
|
<p>When instantiating a <code>QueueRequestHandler</code>
|
|
the <code>$request</code>
|
|
property is initially set by fetching the actual server
|
|
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>
|
|
|
|
</div>
|
|
|
|
<div class="section" id="http-response">
|
|
<h3>HTTP Response</h3>
|
|
|
|
|
|
<p>The response can be read as <code>QueueRequestHandler::response</code>
|
|
. It also follows PHP-FIG'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/#33-psrhttpmessageresponseinterface">Psr\Http\Message\ResponseInterface</a>.</p>
|
|
|
|
|
|
<p>When instantiating a <code>QueueRequestHandler</code>
|
|
the <code>$response</code>
|
|
property is initially set as a blank HTTP response with
|
|
status code <code>200</code>
|
|
. The property is reset each time the response is passed through a middleware and thus
|
|
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>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class="section" id="methods">
|
|
<h2>Methods</h2>
|
|
|
|
|
|
<p>The <code>QueueRequestHandler</code>
|
|
provides two public API methods, <a href="classes/OCC-PSR15-QueueRequestHandler.html#method_handle"><abbr title="\OCC\PSR15\QueueRequestHandler::handle()">QueueRequestHandler::handle()</abbr></a>
|
|
and
|
|
<a href="classes/OCC-PSR15-QueueRequestHandler.html#method_respond"><abbr title="\OCC\PSR15\QueueRequestHandler::respond()">QueueRequestHandler::respond()</abbr></a>
|
|
. As their names suggest, the former handles the server request
|
|
while the latter sends the response back to the client. Invoking the request handler object directly does the same as
|
|
calling the <code>handle()</code>
|
|
method.</p>
|
|
|
|
<div class="section" id="handling-a-server-request">
|
|
<h3>Handling a Server Request</h3>
|
|
|
|
|
|
<p>After adding at least one middleware to the queue, you can start handling a request by simply calling
|
|
<a href="classes/OCC-PSR15-QueueRequestHandler.html#method_handle"><abbr title="\OCC\PSR15\QueueRequestHandler::handle()">QueueRequestHandler::handle()</abbr></a>
|
|
. Optionally, you can pass a request object as argument, but since
|
|
the actual server request was already fetched in the constructor and will be used by default, most of the time you
|
|
don't need to. All request objects must implement <code>Psr\Http\Message\ServerRequestInterface</code>
|
|
.</p>
|
|
|
|
|
|
<p>The <code>handle()</code>
|
|
method returns the final response after passing it through all middlewares. The response object always
|
|
implements <code>Psr\Http\Message\ResponseInterface</code>
|
|
.</p>
|
|
|
|
|
|
<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's within the valid range of HTTP status codes, otherwise it's set to <code>500 (Internal Server Error)</code>
|
|
), and
|
|
the exception message as body.</p>
|
|
|
|
</div>
|
|
|
|
<div class="section" id="sending-the-response">
|
|
<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>
|
|
.
|
|
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>
|
|
|
|
</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>
|