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

View File

@ -22,13 +22,13 @@ declare(strict_types=1);
namespace OCC\PSR15;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as ServerRequest;
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>
* @package PSR15
@ -37,19 +37,24 @@ abstract class AbstractMiddleware implements MiddlewareInterface
{
/**
* The PSR-15 Server Request Handler.
*
* @var QueueRequestHandler
*
* @internal
*/
protected QueueRequestHandler $requestHandler;
/**
* Process an incoming server request and produce a response.
* @see MiddlewareInterface::process()
*
* @param ServerRequestInterface $request The server request to process
* @param RequestHandlerInterface $handler The request handler to delegate to
* @param ServerRequest $request The server request to process
* @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 */
$this->requestHandler = $handler;
@ -66,11 +71,11 @@ abstract class AbstractMiddleware implements MiddlewareInterface
/**
* 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;
}
@ -78,25 +83,26 @@ abstract class AbstractMiddleware implements MiddlewareInterface
/**
* 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;
}
/**
* Allow the middleware to be invoked directly.
* @see AbstractMiddleware::process()
*
* @param ServerRequestInterface $request The server request to process
* @param RequestHandlerInterface $handler The request handler to delegate to
* @param ServerRequest $request The server request to process
* @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);
}

View File

@ -24,7 +24,7 @@ namespace OCC\PSR15;
use OCC\Basics\DataStructures\StrictQueue;
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.
@ -32,7 +32,9 @@ use Psr\Http\Server\MiddlewareInterface;
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package PSR15
*
* @extends StrictQueue<MiddlewareInterface>
* @method static static getInstance(iterable<\Psr\Http\Server\MiddlewareInterface> $middlewares)
*
* @extends StrictQueue<Middleware>
*/
class MiddlewareQueue extends StrictQueue
{
@ -41,11 +43,13 @@ class MiddlewareQueue extends StrictQueue
/**
* 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 = [])
{
parent::__construct([MiddlewareInterface::class]);
parent::__construct([Middleware::class]);
$this->append(...$middlewares);
}
}

View File

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