sebastian-meyer
/
psr-15
mirror of https://github.com/opencultureconsulting/psr-15.git
2
0
Fork 0
Code Issues

Update phpDocs

This commit is contained in:
Sebastian Meyer 2024-03-31 19:29:57 +02:00
parent 7128019a09
commit 6716ac6d26
3 changed files with 98 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
src/AbstractMiddleware.php
View File

@ -22,13 +22,13 @@ declare(strict_types=1);
namespace OCC\PSR15; namespace OCC\PSR15;
use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Message\ServerRequestInterface as ServerRequest;
use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface; use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
/** /**
* Abstract class implementing Psr\Http\Server\MiddlewareInterface. * Abstract class implementing \Psr\Http\Server\MiddlewareInterface.
* *
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com> * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package PSR15 * @package PSR15
@ -37,19 +37,24 @@ abstract class AbstractMiddleware implements MiddlewareInterface
{ {
/** /**
* The PSR-15 Server Request Handler. * The PSR-15 Server Request Handler.
*
* @var QueueRequestHandler
*
* @internal
*/ */
protected QueueRequestHandler $requestHandler; protected QueueRequestHandler $requestHandler;
/** /**
* Process an incoming server request and produce a response. * Process an incoming server request and produce a response.
* @see MiddlewareInterface::process()
* *
* @param ServerRequestInterface $request The server request to process * @param ServerRequest $request The server request to process
* @param RequestHandlerInterface $handler The request handler to delegate to * @param RequestHandler $handler The request handler to delegate to
* *
* @return ResponseInterface The response object * @return Response The response object
*
* @api
*/ */
final public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface final public function process(ServerRequest $request, RequestHandler $handler): Response
{ {
/** @var QueueRequestHandler $handler */ /** @var QueueRequestHandler $handler */
$this->requestHandler = $handler; $this->requestHandler = $handler;
@ -66,11 +71,11 @@ abstract class AbstractMiddleware implements MiddlewareInterface
/** /**
* Process an incoming server request before delegating to next middleware. * Process an incoming server request before delegating to next middleware.
* *
* @param ServerRequestInterface $request The incoming server request * @param ServerRequest $request The incoming server request
* *
* @return ServerRequestInterface The processed server request * @return ServerRequest The processed server request
*/ */
protected function processRequest(ServerRequestInterface $request): ServerRequestInterface protected function processRequest(ServerRequest $request): ServerRequest
{ {
return $request; return $request;
} }
@ -78,25 +83,26 @@ abstract class AbstractMiddleware implements MiddlewareInterface
/** /**
* Process an incoming response before returning it to previous middleware. * Process an incoming response before returning it to previous middleware.
* *
* @param ResponseInterface $response The incoming response * @param Response $response The incoming response
* *
* @return ResponseInterface The processed response * @return Response The processed response
*/ */
protected function processResponse(ResponseInterface $response): ResponseInterface protected function processResponse(Response $response): Response
{ {
return $response; return $response;
} }
/** /**
* Allow the middleware to be invoked directly. * Allow the middleware to be invoked directly.
* @see AbstractMiddleware::process()
* *
* @param ServerRequestInterface $request The server request to process * @param ServerRequest $request The server request to process
* @param RequestHandlerInterface $handler The request handler to delegate to * @param RequestHandler $handler The request handler to delegate to
* *
* @return ResponseInterface The response object * @return Response The response object
*
* @api
*/ */
final public function __invoke(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface final public function __invoke(ServerRequest $request, RequestHandler $handler): Response
{ {
return $this->process($request, $handler); return $this->process($request, $handler);
} }

12
src/MiddlewareQueue.php
View File

@ -24,7 +24,7 @@ namespace OCC\PSR15;
use OCC\Basics\DataStructures\StrictQueue; use OCC\Basics\DataStructures\StrictQueue;
use OCC\Basics\Traits\Singleton; use OCC\Basics\Traits\Singleton;
use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\MiddlewareInterface as Middleware;
/** /**
* Queue of PSR-15 Middlewares to process HTTP Server Requests. * Queue of PSR-15 Middlewares to process HTTP Server Requests.
@ -32,7 +32,9 @@ use Psr\Http\Server\MiddlewareInterface;
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com> * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package PSR15 * @package PSR15
* *
* @extends StrictQueue<MiddlewareInterface> * @method static static getInstance(iterable<\Psr\Http\Server\MiddlewareInterface> $middlewares)
*
* @extends StrictQueue<Middleware>
*/ */
class MiddlewareQueue extends StrictQueue class MiddlewareQueue extends StrictQueue
{ {
@ -41,11 +43,13 @@ class MiddlewareQueue extends StrictQueue
/** /**
* Create a queue of PSR-15 compatible middlewares. * Create a queue of PSR-15 compatible middlewares.
* *
* @param iterable<MiddlewareInterface> $middlewares Initial set of PSR-15 middlewares * @param iterable<array-key, Middleware> $middlewares Initial set of PSR-15 middlewares
*
* @return void
*/ */
private function __construct(iterable $middlewares = []) private function __construct(iterable $middlewares = [])
{ {
parent::__construct([MiddlewareInterface::class]); parent::__construct([Middleware::class]);
$this->append(...$middlewares); $this->append(...$middlewares);
} }
} }

95
src/QueueRequestHandler.php
View File

@ -24,13 +24,22 @@ namespace OCC\PSR15;
use Exception; use Exception;
use RuntimeException; use RuntimeException;
use GuzzleHttp\Psr7\Response; use GuzzleHttp\Psr7\Response as GuzzleResponse;
use GuzzleHttp\Psr7\ServerRequest; use GuzzleHttp\Psr7\ServerRequest as GuzzleRequest;
use OCC\Basics\Traits\Getter; use OCC\Basics\Traits\Getter;
use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Message\ServerRequestInterface as ServerRequest;
use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\MiddlewareInterface as Middleware;
use Psr\Http\Server\RequestHandlerInterface; use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
use function array_keys;
use function count;
use function filter_var;
use function get_debug_type;
use function header;
use function headers_sent;
use function is_null;
use function sprintf;
/** /**
* A queue-based PSR-15 HTTP Server Request Handler. * A queue-based PSR-15 HTTP Server Request Handler.
@ -39,35 +48,50 @@ use Psr\Http\Server\RequestHandlerInterface;
* @package PSR15 * @package PSR15
* *
* @property-read MiddlewareQueue $queue * @property-read MiddlewareQueue $queue
* @property-read ServerRequestInterface $request * @property-read ServerRequest $request
* @property-read Response $response
*/ */
class QueueRequestHandler implements RequestHandlerInterface class QueueRequestHandler implements RequestHandler
{ {
use Getter; use Getter;
/** /**
* The PSR-7 HTTP Server Request. * The PSR-7 HTTP Server Request.
*
* @var ServerRequest
*
* @internal
*/ */
protected ServerRequestInterface $request; protected ServerRequest $request;
/** /**
* The queue of middlewares to process the server request. * The queue of middlewares to process the server request.
*
* @var MiddlewareQueue
*
* @internal
*/ */
protected MiddlewareQueue $queue; protected MiddlewareQueue $queue;
/** /**
* The PSR-7 HTTP Response. * The PSR-7 HTTP Response.
*
* @var Response
*
* @internal
*/ */
protected ResponseInterface $response; protected Response $response;
/** /**
* Handles a request by invoking a queue of middlewares. * Handles a request by invoking a queue of middlewares.
* *
* @param ?ServerRequestInterface $request The PSR-7 server request to handle * @param ?ServerRequest $request The PSR-7 server request to handle
* *
* @return ResponseInterface A PSR-7 compatible HTTP response * @return Response A PSR-7 compatible HTTP response
*
* @api
*/ */
public function handle(?ServerRequestInterface $request = null): ResponseInterface public function handle(?ServerRequest $request = null): Response
{ {
$this->request = $request ?? $this->request; $this->request = $request ?? $this->request;
if (count($this->queue) > 0) { if (count($this->queue) > 0) {
@ -78,7 +102,7 @@ class QueueRequestHandler implements RequestHandlerInterface
// further processing to ensure that a response is always generated. // further processing to ensure that a response is always generated.
try { try {
$this->response = $middleware->process($this->request, $this); $this->response = $middleware->process($this->request, $this);
} catch(Exception $exception) { } catch (Exception $exception) {
$options = [ $options = [
'options' => [ 'options' => [
'default' => 500, 'default' => 500,
@ -87,7 +111,7 @@ class QueueRequestHandler implements RequestHandlerInterface
] ]
]; ];
$statusCode = filter_var($exception->getCode(), FILTER_VALIDATE_INT, $options); $statusCode = filter_var($exception->getCode(), FILTER_VALIDATE_INT, $options);
$this->response = new Response( $this->response = new GuzzleResponse(
$statusCode, $statusCode,
[], [],
sprintf( sprintf(
@ -109,7 +133,9 @@ class QueueRequestHandler implements RequestHandlerInterface
* *
* @return void * @return void
* *
* @throws RuntimeException * @throws RuntimeException if headers were already sent
*
* @api
*/ */
public function respond(?int $exitCode = null): void public function respond(?int $exitCode = null): void
{ {
@ -126,7 +152,7 @@ class QueueRequestHandler implements RequestHandlerInterface
} }
header( header(
sprintf( sprintf(
'HTTP/%s %s %s', 'HTTP/%s %d %s',
$this->response->getProtocolVersion(), $this->response->getProtocolVersion(),
$this->response->getStatusCode(), $this->response->getStatusCode(),
$this->response->getReasonPhrase() $this->response->getReasonPhrase()
@ -134,6 +160,7 @@ class QueueRequestHandler implements RequestHandlerInterface
true true
); );
foreach (array_keys($this->response->getHeaders()) as $name) { foreach (array_keys($this->response->getHeaders()) as $name) {
/** @var string $name */
$header = sprintf('%s: %s', $name, $this->response->getHeaderLine($name)); $header = sprintf('%s: %s', $name, $this->response->getHeaderLine($name));
header($header, false); header($header, false);
} }
@ -145,9 +172,10 @@ class QueueRequestHandler implements RequestHandlerInterface
/** /**
* Magic getter method for $this->queue. * Magic getter method for $this->queue.
* @see Getter
* *
* @return MiddlewareQueue The queue of PSR-15 middlewares * @return MiddlewareQueue The queue of PSR-15 middlewares
*
* @internal
*/ */
protected function magicGetQueue(): MiddlewareQueue protected function magicGetQueue(): MiddlewareQueue
{ {
@ -156,22 +184,24 @@ class QueueRequestHandler implements RequestHandlerInterface
/** /**
* Magic getter method for $this->request. * Magic getter method for $this->request.
* @see Getter
* *
* @return ServerRequestInterface The PSR-7 server request * @return ServerRequest The PSR-7 server request
*
* @internal
*/ */
protected function magicGetRequest(): ServerRequestInterface protected function _magicGetRequest(): ServerRequest
{ {
return $this->request; return $this->request;
} }
/** /**
* Magic getter method for $this->response. * Magic getter method for $this->response.
* @see Getter
* *
* @return ResponseInterface The PSR-7 response * @return Response The PSR-7 response
*
* @internal
*/ */
protected function magicGetResponse(): ResponseInterface protected function _magicGetResponse(): Response
{ {
return $this->response; return $this->response;
} }
@ -179,24 +209,27 @@ class QueueRequestHandler implements RequestHandlerInterface
/** /**
* Create a queue-based PSR-15 HTTP Server Request Handler. * Create a queue-based PSR-15 HTTP Server Request Handler.
* *
* @param iterable<MiddlewareInterface> $middlewares Initial set of middlewares * @param iterable<array-key, Middleware> $middlewares Initial set of middlewares
*
* @return void
*/ */
public function __construct(iterable $middlewares = []) public function __construct(iterable $middlewares = [])
{ {
$this->request = ServerRequest::fromGlobals(); $this->request = GuzzleRequest::fromGlobals();
$this->queue = MiddlewareQueue::getInstance($middlewares); $this->queue = MiddlewareQueue::getInstance($middlewares);
$this->response = new Response(200); $this->response = new GuzzleResponse(200);
} }
/** /**
* Allow the request handler to be invoked directly. * Allow the request handler to be invoked directly.
* @see QueueRequestHandler::handle()
* *
* @param ?ServerRequestInterface $request The PSR-7 server request to handle * @param ?ServerRequest $request The PSR-7 server request to handle
* *
* @return ResponseInterface A PSR-7 compatible HTTP response * @return Response A PSR-7 compatible HTTP response
*
* @api
*/ */
public function __invoke(?ServerRequestInterface $request = null): ResponseInterface public function __invoke(?ServerRequest $request = null): Response
{ {
return $this->handle($request); return $this->handle($request);
} }