From d8b25299b2aadb384ba307001e84d093000f27a3 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Sat, 13 Jul 2024 15:21:05 +0200 Subject: [PATCH] Update documentation for AbstractMiddleware --- .phpdoc/guide/overview/abstractmiddleware.rst | 48 ++++++++ doc/guides/overview/abstractmiddleware.html | 109 ++++++++++++++++++ doc/guides/overview/index.html | 13 +++ 3 files changed, 170 insertions(+) diff --git a/.phpdoc/guide/overview/abstractmiddleware.rst b/.phpdoc/guide/overview/abstractmiddleware.rst index b638b92..759fa46 100644 --- a/.phpdoc/guide/overview/abstractmiddleware.rst +++ b/.phpdoc/guide/overview/abstractmiddleware.rst @@ -3,3 +3,51 @@ AbstractMiddleware ################## +.. sidebar:: Table of Contents + .. contents:: + +The `AbstractMiddleware` is a little helper for creating your own middlewares. It processes the incoming request before +handing it over to the next middleware in line, and later processes the response before returning it to the previous +middleware. Originally both methods just return their argument unchanged, so you should implement either one of them or +both as needed. + +The `AbstractMiddleware` implements the +`Psr\Http\Server\MiddlewareInterface `_ +following PHP-FIG's recommendation `PSR-15: HTTP Server Request Handlers `_. + +Properties +========== + +The `AbstractMiddleware` has a single protected property `AbstractMiddleware::requestHandler` referencing the request +handler which called the middleware. This can be used to access the request and/or response object (as properties of +:doc:`queuerequesthandler`) when they are otherwise not available. + +Methods +======= + +The `AbstractMiddleware` provides one public API method and two protected methods. While the former is final and makes +sure it implements the `Psr\Http\Server\MiddlewareInterface`, the latter are intended to be extended in your own class. + +The main :php:method:`OCC\PSR15\AbstractMiddleware::process()` method implements the interface and is also called when +invoking the middleware object directly. It first passes the incoming request to the +:php:method:`OCC\PSR15\AbstractMiddleware::processRequest()` method, then hands over the result to the request handler +to receive a response, which is then processed by :php:method:`OCC\PSR15\AbstractMiddleware::processResponse()` before +returning it back to the request handler again. + +Processing a Request +-------------------- + +The default method of `AbstractMiddleware` just returns the request unchanged. If you need to process the request, you +have to implement your own `processRequest()` method. It takes a request object as only argument and must return a +valid request object as well. Just make sure it follows PHP-FIG's standard recommendation +`PSR-7: HTTP Message Interfaces `_ and implements the +`Psr\Http\Message\ServerRequestInterface `_. + +Processing a Response +--------------------- + +The default method of `AbstractMiddleware` just returns the response unchanged. If you need to process the response, +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 `_. diff --git a/doc/guides/overview/abstractmiddleware.html b/doc/guides/overview/abstractmiddleware.html index c01576c..5327f1f 100644 --- a/doc/guides/overview/abstractmiddleware.html +++ b/doc/guides/overview/abstractmiddleware.html @@ -153,6 +153,115 @@

AbstractMiddleware

+
+

Table of Contents

+
+ +
+ +
+
+ + +

The AbstractMiddleware + is a little helper for creating your own middlewares. It processes the incoming request before +handing it over to the next middleware in line, and later processes the response before returning it to the previous +middleware. Originally both methods just return their argument unchanged, so you should implement either one of them or +both as needed.

+ + +

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

+ +
+

Properties

+ + +

The AbstractMiddleware + has a single protected property AbstractMiddleware::requestHandler + referencing the request +handler which called the middleware. This can be used to access the request and/or response object (as properties of +QueueRequestHandler) when they are otherwise not available.

+ +
+ +
+

Methods

+ + +

The AbstractMiddleware + provides one public API method and two protected methods. While the former is final and makes +sure it implements the Psr\Http\Server\MiddlewareInterface +, the latter are intended to be extended in your own class.

+ + +

The main AbstractMiddleware::process() + method implements the interface and is also called when +invoking the middleware object directly. It first passes the incoming request to the +AbstractMiddleware::processRequest() + method, then hands over the result to the request handler +to receive a response, which is then processed by AbstractMiddleware::processResponse() + before +returning it back to the request handler again.

+ +
+

Processing a Request

+ + +

The default method of AbstractMiddleware + just returns the request unchanged. If you need to process the request, you +have to implement your own processRequest() + method. It takes a request object as only argument and must return a +valid request object as well. Just make sure it follows PHP-FIG's standard recommendation +PSR-7: HTTP Message Interfaces and implements the +Psr\Http\Message\ServerRequestInterface.

+ +
+ +
+

Processing a Response

+ + +

The default method of AbstractMiddleware + just returns the response unchanged. If you need to process the response, +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.

+ +
+ +
+
diff --git a/doc/guides/overview/index.html b/doc/guides/overview/index.html index 2978bac..3b36583 100644 --- a/doc/guides/overview/index.html +++ b/doc/guides/overview/index.html @@ -203,7 +203,20 @@ in other projects.

  • AbstractMiddleware +