From 02eb93bf3b78c9a52be7548d0b3f607f18edb670 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Sat, 7 Sep 2024 18:52:50 +0200 Subject: [PATCH] Update documentation --- .phpdoc/guide/changelog.rst | 13 +++++ .../guide/overview/queuerequesthandler.rst | 6 +- .phpdoc/template/index.html.twig | 8 ++- .../OCC-PSR15-QueueRequestHandler.html | 43 +++++--------- doc/files/src/QueueRequestHandler.php.txt | 34 ++++------- doc/guides/changelog.html | 55 +++++++++++++++--- doc/guides/index.html | 10 +++- doc/guides/overview/abstractmiddleware.html | 32 ++++++----- doc/guides/overview/index.html | 4 +- doc/guides/overview/middlewarequeue.html | 23 ++++---- doc/guides/overview/queuerequesthandler.html | 56 +++++++++---------- doc/guides/usage/index.html | 4 +- doc/guides/usage/installation.html | 16 +++--- doc/guides/usage/requirements.html | 12 ++-- doc/guides/usage/usage.html | 16 +++--- doc/index.html | 8 ++- 16 files changed, 189 insertions(+), 151 deletions(-) diff --git a/.phpdoc/guide/changelog.rst b/.phpdoc/guide/changelog.rst index 9486680..5ec1f72 100644 --- a/.phpdoc/guide/changelog.rst +++ b/.phpdoc/guide/changelog.rst @@ -6,6 +6,19 @@ Changelog .. sidebar:: Table of Contents .. contents:: +v1.2.0 +====== + +**Minor Changes:** + +* Added a `Warning` header to identify response messages from converted exceptions +* Removed the option to provide an exit status to :php:method:`OCC\PSR15\QueueRequestHandler::respond()` +* Added Composer command for development tools (PHP Mess Detector, Psalm Taint Analysis) + +**Maintencance:** + +* Updated dependencies + v1.1.0 ====== diff --git a/.phpdoc/guide/overview/queuerequesthandler.rst b/.phpdoc/guide/overview/queuerequesthandler.rst index a59665e..36ea86a 100644 --- a/.phpdoc/guide/overview/queuerequesthandler.rst +++ b/.phpdoc/guide/overview/queuerequesthandler.rst @@ -97,12 +97,10 @@ 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. +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()`. -Optionally, you can provide an exit code as argument (an integer in the range `0` to `254`). If you do so, script -execution is stopped after sending out the response and the given exit status is set. The status `0` means the request -was handled successfully, every other status is considered an error. diff --git a/.phpdoc/template/index.html.twig b/.phpdoc/template/index.html.twig index ebfd865..a557272 100644 --- a/.phpdoc/template/index.html.twig +++ b/.phpdoc/template/index.html.twig @@ -19,9 +19,11 @@ your own middleware, but you can just as well use any middleware that implements the middleware interface specified by PSR-15 (e.g. from the awesome PSR-15 HTTP Middlewares project).

-

All components of this package follow the highest coding standards of PHPStan - and Psalm, and comply to PSR-12 - code style guidelines to make sure they can be combined and easily re-used in other projects.

+

All components of this package follow the highest coding standards of Psalm, + PHPStan, PHP Mess Detector, + PHP_CodeSniffer, and comply to + PSR-12 code style guidelines to make sure they can be combined + and easily re-used in other projects.

Table of Contents

diff --git a/doc/classes/OCC-PSR15-QueueRequestHandler.html b/doc/classes/OCC-PSR15-QueueRequestHandler.html index 08ce623..ba59625 100644 --- a/doc/classes/OCC-PSR15-QueueRequestHandler.html +++ b/doc/classes/OCC-PSR15-QueueRequestHandler.html @@ -184,9 +184,9 @@

A queue-based PSR-15 HTTP Server Request Handler.

@@ -442,9 +442,9 @@

Create a queue-based PSR-15 HTTP Server Request Handler.

@@ -490,9 +490,9 @@

Allow the request handler to be invoked directly.

@@ -546,9 +546,9 @@

Handles a request by invoking a queue of middlewares.

@@ -604,16 +604,16 @@

Return the current response to the client.

public - respond([int|null $exitCode = null ]) : void + respond() : void
APIYes
@@ -621,20 +621,7 @@
-
Parameters
-
-
- $exitCode - : int|null - = null
-
-

Exit status after sending out the response or NULL to continue

-

Must be in the range 0 to 254. The status 0 is used to terminate the program successfully.

-
- -
-
- +
Tags @@ -771,9 +758,9 @@
  • Properties
    • diff --git a/doc/files/src/QueueRequestHandler.php.txt b/doc/files/src/QueueRequestHandler.php.txt index 5dab177..0b165d7 100644 --- a/doc/files/src/QueueRequestHandler.php.txt +++ b/doc/files/src/QueueRequestHandler.php.txt @@ -38,7 +38,6 @@ use function filter_var; use function get_debug_type; use function header; use function headers_sent; -use function is_null; use function sprintf; /** @@ -110,12 +109,18 @@ class QueueRequestHandler implements RequestHandler 'max_range' => 599 ] ]; - $statusCode = filter_var($exception->getCode(), FILTER_VALIDATE_INT, $options); $this->response = new GuzzleResponse( - $statusCode, - [], + filter_var($exception->getCode(), FILTER_VALIDATE_INT, $options), + [ + 'Warning' => [sprintf( + 'Error %d in %s', + $exception->getCode(), + get_debug_type($middleware) + )] + ], sprintf( - 'Exception thrown in middleware %s: %s', + 'Exception %d thrown in middleware %s: %s', + $exception->getCode(), get_debug_type($middleware), $exception->getMessage() ) @@ -128,17 +133,13 @@ class QueueRequestHandler implements RequestHandler /** * Return the current response to the client. * - * @param ?int $exitCode Exit status after sending out the response or NULL to continue - * - * Must be in the range 0 to 254. The status 0 is used to terminate the program successfully. - * * @return void * * @throws RuntimeException if headers were already sent * * @api */ - public function respond(?int $exitCode = null): void + public function respond(): void { $file = 'unknown file'; $line = 0; @@ -166,17 +167,6 @@ class QueueRequestHandler implements RequestHandler header($header, false); } echo $this->response->getBody(); - if (!is_null($exitCode)) { - $options = [ - 'options' => [ - 'default' => 1, - 'min_range' => 0, - 'max_range' => 254 - ] - ]; - $exitCode = filter_var($exitCode, FILTER_VALIDATE_INT, $options); - exit($exitCode); - } } /** @@ -226,7 +216,7 @@ class QueueRequestHandler implements RequestHandler { $this->request = GuzzleRequest::fromGlobals(); $this->queue = MiddlewareQueue::getInstance($middlewares); - $this->response = new GuzzleResponse(200); + $this->response = new GuzzleResponse(); } /** diff --git a/doc/guides/changelog.html b/doc/guides/changelog.html index ff7ad4b..481ef1b 100644 --- a/doc/guides/changelog.html +++ b/doc/guides/changelog.html @@ -150,7 +150,7 @@
    -
    +

    Changelog

    @@ -158,6 +158,12 @@
    -
    +
    +

    v1.2.0

    + + +

    Minor Changes: +

    + + + +
      +
    • Added a Warning + header to identify response messages from converted exceptions
      • + +
    • Removed the option to provide an exit status to QueueRequestHandler::respond() +
      • + +
    • Added Composer command for development tools (PHP Mess Detector, Psalm Taint Analysis)
      • + +
    + + +

    Maintencance: +

    + + + +
      +
    • Updated dependencies
      • + +
    + +
    + +

    v1.1.0

    @@ -217,9 +256,9 @@ -
    +
    -
    +

    v1.0.1

    @@ -233,18 +272,18 @@ -
    + -
    +

    v1.0.0

    Initial Release

    -
    + -
    +
    diff --git a/doc/guides/index.html b/doc/guides/index.html index 7405720..3d914be 100644 --- a/doc/guides/index.html +++ b/doc/guides/index.html @@ -150,7 +150,7 @@
    -
    +

    Documentation

    @@ -209,6 +209,12 @@ Changelog
    -
    +
    diff --git a/doc/guides/overview/abstractmiddleware.html b/doc/guides/overview/abstractmiddleware.html index 5327f1f..062d7ef 100644 --- a/doc/guides/overview/abstractmiddleware.html +++ b/doc/guides/overview/abstractmiddleware.html @@ -150,7 +150,7 @@
    -
    +

    AbstractMiddleware

    @@ -197,11 +197,11 @@ both as needed.

    The AbstractMiddleware - implements the -Psr\Http\Server\MiddlewareInterface -following PHP-FIG's recommendation PSR-15: HTTP Server Request Handlers.

    + implements the Psr\Http\Server\MiddlewareInterface + following PHP-FIG's recommendation +PSR-15: HTTP Server Request Handlers.

    -
    +

    Properties

    @@ -211,9 +211,9 @@ following PHP-FIG's recommendation QueueRequestHandler) when they are otherwise not available.

    -
    +
    - +
    -
    +

    Processing a Response

    @@ -256,13 +257,14 @@ you have to implement your own processResponse() method. It takes a response object as only argument and must return a valid response object as well. Just make sure it follows PHP-FIG's standard recommendation PSR-7: HTTP Message Interfaces and implements the -Psr\Http\Message\ResponseInterface.

    +Psr\Http\Message\ResponseInterface +.

    -
    + - + - +
    diff --git a/doc/guides/overview/index.html b/doc/guides/overview/index.html index 3b36583..188b74f 100644 --- a/doc/guides/overview/index.html +++ b/doc/guides/overview/index.html @@ -150,7 +150,7 @@
    -
    +

    Overview

    @@ -222,7 +222,7 @@ in other projects.

    -
    +
    diff --git a/doc/guides/overview/middlewarequeue.html b/doc/guides/overview/middlewarequeue.html index 11b4394..0afa30c 100644 --- a/doc/guides/overview/middlewarequeue.html +++ b/doc/guides/overview/middlewarequeue.html @@ -150,7 +150,7 @@
    -
    +

    MiddlewareQueue

    @@ -187,7 +187,8 @@ manages the middlewares involved in processing a server request. It makes sure they are called in first-in, first-out (FIFO) order, i.e. the same order they were added to the queue. It also ensures all middlewares are implementing the PSR-15: HTTP Server Request Handlers specification for the -Psr\Http\Server\MiddlewareInterface.

    +Psr\Http\Server\MiddlewareInterface +.

    When instantiating a MiddlewareQueue @@ -215,10 +216,10 @@ $queue->enqueue(new MiddlewareTwo());

    The MiddlewareQueue - is based on a -OCC\Basics\DataStructures\StrictQueue.

    + is based on a OCC\Basics\DataStructures\StrictQueue +.

    -
    +

    Methods

    @@ -233,7 +234,7 @@ returns the first item from the queue.

    For a complete API documentation have a look at the StrictQueue.

    -
    +

    Adding a Middleware

    @@ -247,9 +248,9 @@ criterion an OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException

    Have a look at the AbstractMiddleware for an easy way to create your own middlewares!

    -
    +
    -
    +

    Fetching the next in line

    @@ -263,11 +264,11 @@ Also, this middleware is removed from the queue.

    ) before trying to dequeue an item!

    -
    +
    -
    +
    - +
    diff --git a/doc/guides/overview/queuerequesthandler.html b/doc/guides/overview/queuerequesthandler.html index a57fd83..c47f81e 100644 --- a/doc/guides/overview/queuerequesthandler.html +++ b/doc/guides/overview/queuerequesthandler.html @@ -150,7 +150,7 @@
    -
    +

    QueueRequestHandler

    @@ -215,14 +215,14 @@ 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.

    + 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.

    -     +
    -
    +

    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.

    +Psr\Http\Message\ServerRequestInterface +.

    When instantiating a QueueRequestHandler @@ -286,16 +287,17 @@ $requestHandler->queue->enqueue(new MiddlewareTwo()); 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.

    +Psr\Http\Message\ResponseInterface +.

    When instantiating a QueueRequestHandler @@ -308,11 +310,11 @@ always represents the latest state of the response.

    Both, request and response, use the awesome implementations of Guzzle.

    -
    + - + -
    +

    Methods

    @@ -325,7 +327,7 @@ while the latter sends the response back to the client. Invoking the request han calling the handle() method.

    -
    +

    Handling a Server Request

    @@ -346,28 +348,24 @@ 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.

    +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() -. -Optionally, you can provide an exit code as argument (an integer in the range 0 - to 254 -). If you do so, script -execution is stopped after sending out the response and the given exit status is set. The status 0 - means the request -was handled successfully, every other status is considered an error.

    +.

    -
    + -
    + - +
    diff --git a/doc/guides/usage/index.html b/doc/guides/usage/index.html index b70da21..3ec97d6 100644 --- a/doc/guides/usage/index.html +++ b/doc/guides/usage/index.html @@ -150,7 +150,7 @@
    -
    +

    User Guide

    @@ -233,7 +233,7 @@ application. For a detailed description of the package's contents have a lo
    -
    +
    diff --git a/doc/guides/usage/installation.html b/doc/guides/usage/installation.html index e3c095e..2889a21 100644 --- a/doc/guides/usage/installation.html +++ b/doc/guides/usage/installation.html @@ -150,7 +150,7 @@
    -
    +

    Installation

    @@ -181,7 +181,7 @@
    -
    +

    Composer

    @@ -203,9 +203,9 @@ composer require "opencultureconsulting/psr15:~1.1"

    All available versions as well as further information about Requirements and dependencies can be found on Packagist.

    -
    +
    -
    +

    Git

    @@ -227,18 +227,18 @@ git clone --branch=v1.1.0 https://github.com/opencultureconsulting/psr-15.git ps

    Be aware that you also need to make the classes available in your application by either adding them to your autoloader or by including all files individually in PHP. Also don't forget to do the same for all Requirements.

    -
    + -
    +

    Download

    As a last resort you can also just download the files. You can find all available versions as well as the current development state on the GitHub release page.

    -
    + - +
    diff --git a/doc/guides/usage/requirements.html b/doc/guides/usage/requirements.html index 8aa4324..6603980 100644 --- a/doc/guides/usage/requirements.html +++ b/doc/guides/usage/requirements.html @@ -150,10 +150,10 @@
    -
    +

    Requirements

    -
    +

    Environment

    @@ -165,9 +165,9 @@ although it is technically not strictly required for using any of these classes. But it certainly makes it a lot easier!

    -
    +
    -
    +

    Dependencies

    @@ -184,9 +184,9 @@ of the great guzzlehttp of the opencultureconsulting/basics package which also provides some useful traits.

    -
    +
    - +
    diff --git a/doc/guides/usage/usage.html b/doc/guides/usage/usage.html index 60926f5..2695cef 100644 --- a/doc/guides/usage/usage.html +++ b/doc/guides/usage/usage.html @@ -150,7 +150,7 @@
    -
    +

    Usage

    @@ -188,7 +188,7 @@ and MiddlewareTwo ).

    -
    +

    Middlewares

    @@ -304,9 +304,9 @@ class MiddlewareTwo extends AbstractMiddleware

    Well done! We now have two middlewares.

    -
    +
    -
    +

    Request Handler

    @@ -341,9 +341,9 @@ $requestHandler->respond();

    And that's it!

    -
    +
    -
    +

    Diving Deeper

    @@ -365,9 +365,9 @@ is not MiddlewareTwo response status code to 500 .

    -
    + - +
    diff --git a/doc/index.html b/doc/index.html index d697d4e..257e1b8 100644 --- a/doc/index.html +++ b/doc/index.html @@ -167,9 +167,11 @@ your own middleware, but you can just as well use any middleware that implements the middleware interface specified by PSR-15 (e.g. from the awesome PSR-15 HTTP Middlewares project).

    -

    All components of this package follow the highest coding standards of PHPStan - and Psalm, and comply to PSR-12 - code style guidelines to make sure they can be combined and easily re-used in other projects.

    +

    All components of this package follow the highest coding standards of Psalm, + PHPStan, PHP Mess Detector, + PHP_CodeSniffer, and comply to + PSR-12 code style guidelines to make sure they can be combined + and easily re-used in other projects.

    Table of Contents