From 0f1a7cda1889a34c7ea950aee780bcb2a7c370f0 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Sat, 13 Jul 2024 13:38:28 +0200 Subject: [PATCH] Update documentation for MiddlewareQeue --- .phpdoc/guide/overview/middlewarequeue.rst | 62 ++++++++++ .../guide/overview/queuerequesthandler.rst | 1 - doc/guides/overview/index.html | 7 ++ doc/guides/overview/middlewarequeue.html | 114 ++++++++++++++++++ 4 files changed, 183 insertions(+), 1 deletion(-) diff --git a/.phpdoc/guide/overview/middlewarequeue.rst b/.phpdoc/guide/overview/middlewarequeue.rst index 2d95d87..d652228 100644 --- a/.phpdoc/guide/overview/middlewarequeue.rst +++ b/.phpdoc/guide/overview/middlewarequeue.rst @@ -3,3 +3,65 @@ MiddlewareQueue ############### +.. sidebar:: Table of Contents + .. contents:: + +The `MiddlewareQueue` 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 `_. + +When instantiating a `MiddlewareQueue` it defaults to being empty. But you can optionally pass an iterable set of +middlewares to the constructor which are then put into the queue. To demonstrate, the following examples both have +exactly the same result. + + Examples: + + .. code-block:: php + use OCC\PSR15\MiddlewareQueue; + + $middlewares = [ + new MiddlewareOne(), + new MiddlewareTwo() + ]; + + $queue = new MiddlewareQueue($middlewares); + + .. code-block:: php + use OCC\PSR15\MiddlewareQueue; + + $queue = new MiddlewareQueue(); + + $queue->enqueue(new MiddlewareOne()); + $queue->enqueue(new MiddlewareTwo()); + +The `MiddlewareQueue` is based on a +`OCC\Basics\DataStructures\StrictQueue `_. + +Methods +======= + +The `MiddlewareQueue` provides a set of API methods, with `MiddlewareQueue::enqueue()` and `MiddlewareQueue::dequeue()` +being the most relevant ones. The former will add a new item at the end of the queue while the latter removes and +returns the first item from the queue. + +For a complete API documentation have a look at the +`StrictQueue `_. + +Adding a Middleware +------------------- + +Invoking `MiddlewareQueue::enqueue()` will add a middleware at the end of the queue. The only argument must be a +middleware object implementing the `Psr\Http\Server\MiddlewareInterface`. If the given argument does not meet the +criterion an `OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException` is thrown. + +Have a look at the :doc:`abstractmiddleware` for an easy way to create your own middlewares! + +Fetching the next in line +------------------------- + +Calling `MiddlewareQueue::dequeue()` will return the first middleware from the queue, i.e. the oldest one on the queue. +Also, this middleware is removed from the queue. + +If the queue is empty a `RuntimeException` is thrown, so make sure to check the queue's length (e.g. with `count()`) +before trying to dequeue an item! diff --git a/.phpdoc/guide/overview/queuerequesthandler.rst b/.phpdoc/guide/overview/queuerequesthandler.rst index 8b79587..a2ae33b 100644 --- a/.phpdoc/guide/overview/queuerequesthandler.rst +++ b/.phpdoc/guide/overview/queuerequesthandler.rst @@ -53,7 +53,6 @@ have exactly the same result. $requestHandler->queue->enqueue(new MiddlewareOne()); $requestHandler->queue->enqueue(new MiddlewareTwo()); - HTTP Server Request ------------------- diff --git a/doc/guides/overview/index.html b/doc/guides/overview/index.html index b57b8ba..2978bac 100644 --- a/doc/guides/overview/index.html +++ b/doc/guides/overview/index.html @@ -190,7 +190,14 @@ in other projects.

  • MiddlewareQueue +
  • diff --git a/doc/guides/overview/middlewarequeue.html b/doc/guides/overview/middlewarequeue.html index ce182b3..11b4394 100644 --- a/doc/guides/overview/middlewarequeue.html +++ b/doc/guides/overview/middlewarequeue.html @@ -153,6 +153,120 @@

    MiddlewareQueue

    +
    +

    Table of Contents

    +
    + +
    + +
    +
    + + +

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

    + + +

    When instantiating a MiddlewareQueue + it defaults to being empty. But you can optionally pass an iterable set of +middlewares to the constructor which are then put into the queue. To demonstrate, the following examples both have +exactly the same result.

    + +
    +

    Examples:

    +
    use OCC\PSR15\MiddlewareQueue;
+
+$middlewares = [
+    new MiddlewareOne(),
+    new MiddlewareTwo()
+];
+
+$queue = new MiddlewareQueue($middlewares);
    +
    use OCC\PSR15\MiddlewareQueue;
+
+$queue = new MiddlewareQueue();
+
+$queue->enqueue(new MiddlewareOne());
+$queue->enqueue(new MiddlewareTwo());
    +
    + + +

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

    + +
    +

    Methods

    + + +

    The MiddlewareQueue + provides a set of API methods, with MiddlewareQueue::enqueue() + and MiddlewareQueue::dequeue() + +being the most relevant ones. The former will add a new item at the end of the queue while the latter removes and +returns the first item from the queue.

    + + +

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

    + +
    +

    Adding a Middleware

    + + +

    Invoking MiddlewareQueue::enqueue() + will add a middleware at the end of the queue. The only argument must be a +middleware object implementing the Psr\Http\Server\MiddlewareInterface +. If the given argument does not meet the +criterion an OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException + is thrown.

    + + +

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

    + +
    + +
    +

    Fetching the next in line

    + + +

    Calling MiddlewareQueue::dequeue() + will return the first middleware from the queue, i.e. the oldest one on the queue. +Also, this middleware is removed from the queue.

    + + +

    If the queue is empty a RuntimeException + is thrown, so make sure to check the queue's length (e.g. with count() +) +before trying to dequeue an item!

    + +
    + +
    +