2024-07-11 17:52:26 +02:00
<!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" >
2024-09-07 18:52:50 +02:00
< section class = "section " id = "queuerequesthandler" >
2024-07-11 17:52:26 +02:00
< h1 > QueueRequestHandler< / h1 >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
implements the < code > Psr\Http\Server\RequestHandlerInterface< / code >
following PHP-FIG' s recommendation
< a href = "https://www.php-fig.org/psr/psr-15/" > PSR-15: HTTP Server Request Handlers< / a > .< / p >
2024-07-12 15:29:35 +02:00
< p > For a minimal working example have a look at < a href = "guides/usage/usage.html" > Usage< / a > .< / p >
2024-09-07 18:52:50 +02:00
< section class = "section " id = "properties" >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
< section class = "section " id = "middleware-queue" >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< section class = "section " id = "http-server-request" >
2024-07-12 15:29:35 +02:00
< 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
2024-09-07 18:52:50 +02:00
< code > Psr\Http\Message\ServerRequestInterface< / code >
.< / p >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< section class = "section " id = "http-response" >
2024-07-12 15:29:35 +02:00
< 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
2024-09-07 18:52:50 +02:00
< code > Psr\Http\Message\ResponseInterface< / code >
.< / p >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< section class = "section " id = "methods" >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
< section class = "section " id = "handling-a-server-request" >
2024-07-12 15:29:35 +02:00
< 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
2024-09-07 18:52:50 +02:00
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 >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< section class = "section " id = "sending-the-response" >
2024-07-12 15:29:35 +02:00
< 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 >
2024-09-07 18:52:50 +02:00
.< / p >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< / section >
2024-07-12 15:29:35 +02:00
2024-09-07 18:52:50 +02:00
< / section >
2024-07-11 17:52:26 +02:00
< / 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 >
