relay / middleware
Relay-compatible middleware decorators.
Installs: 236 011
Dependents: 14
Suggesters: 0
Security: 0
Stars: 41
Watchers: 2
Forks: 7
Open Issues: 3
Requires
- psr/http-message: ~1.0
Requires (Dev)
README
This package include the following Relay-compatible middleware:
- ExceptionHandler to handle exceptions from subsequent middleware
- FormContentHandler to deserialize the URL-encoded payload of a PSR-7 request
- JsonContentHandler to deserialize the JSON payload of a PSR-7 request
- JsonDecoder to deserialize the JSON payload of a PSR-7 request (deprecated)
- ResponseSender to send a PSR-7 response
- SessionHeadersHandler to manage session headers "manually", instead of PHP managing them automatically
- StatelessExceptionHandler to handle exceptions from subsequent middleware (suitable for multiple request/response cycles)
This package is installable and PSR-4 autoloadable via Composer as relay/middleware
.
ExceptionHandler
Similarly, the ExceptionHandler does what it sound like: it catches any exceptions that bubble up through the subsequent middleware decorators.
The ExceptionHandler does nothing with the $request
or $response
, and passes them directly to $next
inside a try/catch
block. If no exception bubbles up, it returns the $response
from $next
. However, if it catches an exception, it returns an entirely new $response
object with the exception message and an HTTP 500 status code. It then returns the new $response
object.
The ExceptionHandler is intended to go near the top of the Relay queue, but after the ResponseSender, so that the ResponseSender can then send the returned $response
.
To add the ExceptionHandler to your queue, instantiate it directly with an empty $response implementation object ...
$queue[] = new \Relay\Middleware\ExceptionHandler(new ResponseImplementation());
... or use a $resolver
of your choice to instantiate it from the $queue
.
FormContentHandler
FormContentHandler works almost identically to JsonContentHandler (below), but parses payloads of requests that have application/x-www-form-urlencoded
as the Content-Type
.
JsonContentHandler
Again, the JsonContentHandler does what it sounds like: it deserializes the JSON payload of a PSR-7 request object and makes the parameters available in subsequent middleware decorators.
The JsonContentHandler checks the incoming request for a method other than GET
and for an application/json
or application/vnd.api+json
Content-Type
header.
If it finds both of these, it parses the JSON and makes it available as the
parsed body of the $request
before passing it and the $response
to $next
.
If the method is GET
or the Content-Type
header defines a different mime type,
the JsonContentHandler ignores the $request
and continues the chain.
To add the JsonContentHandler to your queue, instantiate it directly...
$queue[] = new \Relay\Middleware\JsonContentHandler();
... or use a $resolver
of your choice to instantiate it from the $queue
.
To access the decoded parameters in subsequent middleware, use the
getParsedBody()
method of the $request
$decodedJsonData = $request->getParsedBody();
JsonDecoder
NOTE: This handler has been deprecated in favor of JsonContentHandler!
Again, the JsonDecoder does what it sounds like: it deserializes the JSON payload of a PSR-7 request object and makes the parameters available in subsequent middleware decorators.
The JsonDecoder checks the incoming request for a method other than GET
and
for an application/json
Content-Type
header. If it finds both of these, it
decodes the JSON and makes it available as the parsed body of the $request
before passing it and the $response
to $next
. If the method is GET
or the
Content-Type
header does not specify application/json
, the JsonDecoder
does nothing with the $request
and passes it and the $response
to $next
.
To add the JsonDecoder to your queue, instantiate it directly...
$queue[] = new \Relay\Middleware\JsonDecoder();
... or use a $resolver
of your choice to instantiate it from the $queue
.
To access the decoded parameters in subsequent middleware, use the
getParsedBody()
method of the $request
$decodedJsonData = $request->getParsedBody();
ResponseSender
The ResponseSender does just what it sounds like: it sends the PSR-7 response object.
The ResponseSender does nothing with the $request
or $response
, passing them immediately to $next
. Afterwards, it takes the returned $response
and sends it using header()
and echo
, and returns the sent $response
.
The ResponseSender is intended to go at the top of the Relay queue, so that it is the middleware with the last opportunity to do something with the returned response.
To add the ResponseSender to your Relay queue, instantiate it directly ...
$queue[] = new \Relay\Middleware\ResponseSender();
... or use a $resolver
of your choice to instantiate it from the $queue
.
SessionHeadersHandler
Normally, PHP will send out headers for you automatically when you call session_start()
. However, this means the headers are not being sent as part of the PSR-7 response object, and are thus outside your control. This handler puts them back under your control by placing the relevant headers in the PSR-7 response; its behavior is almost identical to the native PHP automatic session headers behavior.
NOTE: For this middleware to work, you must disable the PHP session header management ini settings. For example:
ini_set('session.use_trans_sid', false); ini_set('session.use_cookies', false); ini_set('session.use_only_cookies', true); ini_set('session.cache_limiter', '');
If you do not, the handler will throw a RuntimeException.
To add the SessionHeadersHandler to your queue, instantiate it directly...
$queue[] = new \Relay\Middleware\SessionHeadersHandler();
... or use a $resolver
of your choice to instantiate it from the $queue
.
When instantiating, you can pass a cache limiter value as the first constructor parameter. The allowed values are 'nocache', 'public', 'private_no_cache', or 'private'. If you want no cache limiter header at all, pass an empty string ''. The default is 'nocache'.
You can also pass a cache expire value, in minutes, as the second constructor parameter. The default is 180 minutes.
StatelessExceptionHandler
The StatelessExceptionHandler behaves the same as the ExceptionHandler. The difference is that it is suitable for use in environments where it may be used multiple times.
To add the StatelessExceptionHandler to your queue, instantiate it directly with a factory that can be used to create $response objects ...
$responseFactory = function () { return new ResponseImplementation(); }; $queue[] = new \Relay\Middleware\StatelessExceptionHandler($responseFactory);