PSR-15 Queue

QueueRequestHandler

Table of 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.

For a minimal working example have a look at 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 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:

use OCC\PSR15\QueueRequestHandler;

$middlewares = [
    new MiddlewareOne(),
    new MiddlewareTwo()
];

$requestHandler = new QueueRequestHandler($middlewares);
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 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 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.

Methods

The QueueRequestHandler provides two public API methods, QueueRequestHandler::handle() and 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 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 QueueRequestHandler::respond() .

Search results