107 lines
4.7 KiB
ReStructuredText
107 lines
4.7 KiB
ReStructuredText
.. title:: QueueRequestHandler
|
|
|
|
QueueRequestHandler
|
|
###################
|
|
|
|
.. sidebar:: Table of Contents
|
|
.. contents::
|
|
|
|
The `QueueRequestHandler` 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.
|
|
|
|
The `QueueRequestHandler` implements the `Psr\Http\Server\RequestHandlerInterface` following PHP-FIG's recommendation
|
|
`PSR-15: HTTP Server Request Handlers <https://www.php-fig.org/psr/psr-15/>`_.
|
|
|
|
For a minimal working example have a look at :doc:`../usage/usage`.
|
|
|
|
Properties
|
|
==========
|
|
|
|
The `QueueRequestHandler` has three **read-only** properties. They are initially set at instantiation and can be
|
|
directly accessed from the object via magic methods (e.g. `$requestHandler->queue`).
|
|
|
|
Middleware Queue
|
|
----------------
|
|
|
|
The queue of middlewares can be accessed as `QueueRequestHandler::queue` and offers a handy API to `enqueue()`,
|
|
`dequeue()` or otherwise manipulate its contents. All middlewares must implement `Psr\Http\Server\MiddlewareInterface`.
|
|
Have a look at :doc:`middlewarequeue` for more details.
|
|
|
|
When instantiating a `QueueRequestHandler` 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.
|
|
|
|
Examples:
|
|
|
|
.. code-block:: php
|
|
use OCC\PSR15\QueueRequestHandler;
|
|
|
|
$middlewares = [
|
|
new MiddlewareOne(),
|
|
new MiddlewareTwo()
|
|
];
|
|
|
|
$requestHandler = new QueueRequestHandler($middlewares);
|
|
|
|
.. code-block:: php
|
|
use OCC\PSR15\QueueRequestHandler;
|
|
|
|
$requestHandler = new QueueRequestHandler();
|
|
|
|
$requestHandler->queue->enqueue(new MiddlewareOne());
|
|
$requestHandler->queue->enqueue(new MiddlewareTwo());
|
|
|
|
HTTP Server Request
|
|
-------------------
|
|
|
|
The server request is always available as `QueueRequestHandler::request`. It follows PHP-FIG's standard recommendation
|
|
`PSR-7: HTTP Message Interfaces <https://www.php-fig.org/psr/psr-7/>`_ and implements the
|
|
`Psr\Http\Message\ServerRequestInterface`.
|
|
|
|
When instantiating a `QueueRequestHandler` the `$request` 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.
|
|
|
|
HTTP Response
|
|
-------------
|
|
|
|
The response can be read as `QueueRequestHandler::response`. It also follows PHP-FIG's standard recommendation
|
|
`PSR-7: HTTP Message Interfaces <https://www.php-fig.org/psr/psr-7/>`_ and implements the
|
|
`Psr\Http\Message\ResponseInterface`.
|
|
|
|
When instantiating a `QueueRequestHandler` the `$response` property is initially set as a blank HTTP response with
|
|
status code `200`. The property is reset each time the response is passed through a middleware and thus
|
|
always represents the latest state of the response.
|
|
|
|
Both, request and response, use the awesome implementations of `Guzzle <https://github.com/guzzle/psr7>`_.
|
|
|
|
Methods
|
|
=======
|
|
|
|
The `QueueRequestHandler` provides two public API methods, :php:method:`OCC\PSR15\QueueRequestHandler::handle()` and
|
|
:php:method:`OCC\PSR15\QueueRequestHandler::respond()`. 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 `handle()` method.
|
|
|
|
Handling a Server Request
|
|
-------------------------
|
|
|
|
After adding at least one middleware to the queue, you can start handling a request by simply calling
|
|
:php:method:`OCC\PSR15\QueueRequestHandler::handle()`. 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 `Psr\Http\Message\ServerRequestInterface`.
|
|
|
|
The `handle()` method returns the final response after passing it through all middlewares. The response object always
|
|
implements `Psr\Http\Message\ResponseInterface`.
|
|
|
|
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 `500 (Internal Server Error)`), and
|
|
the exception message as body. Such a response can be identified by having a `Warning` header set including the error
|
|
code and the affected middleware.
|
|
|
|
Sending the Response
|
|
--------------------
|
|
|
|
Sending the final response to the client is as easy as calling :php:method:`OCC\PSR15\QueueRequestHandler::respond()`.
|