Update phpDocs

.gitattributes

@@ -0,0 +1,121 @@
+###
+# https://github.com/gitattributes/gitattributes/blob/master/Common.gitattributes
+###
+
+# Auto detect text files and perform LF normalization
+*          text=auto
+
+#
+# The above will handle all files NOT found below
+#
+
+# Documents
+*.bibtex   text diff=bibtex
+*.doc      diff=astextplain
+*.DOC      diff=astextplain
+*.docx     diff=astextplain
+*.DOCX     diff=astextplain
+*.dot      diff=astextplain
+*.DOT      diff=astextplain
+*.pdf      diff=astextplain
+*.PDF      diff=astextplain
+*.rtf      diff=astextplain
+*.RTF      diff=astextplain
+*.md       text diff=markdown
+*.mdx      text diff=markdown
+*.tex      text diff=tex
+*.adoc     text
+*.textile  text
+*.mustache text
+*.csv      text eol=crlf
+*.tab      text
+*.tsv      text
+*.txt      text
+*.sql      text
+*.epub     diff=astextplain
+
+# Graphics
+*.png      binary
+*.jpg      binary
+*.jpeg     binary
+*.gif      binary
+*.tif      binary
+*.tiff     binary
+*.ico      binary
+# SVG treated as text by default.
+*.svg      text
+# If you want to treat it as binary,
+# use the following line instead.
+# *.svg    binary
+*.eps      binary
+
+# Scripts
+*.bash     text eol=lf
+*.fish     text eol=lf
+*.ksh      text eol=lf
+*.sh       text eol=lf
+*.zsh      text eol=lf
+# These are explicitly windows files and should use crlf
+*.bat      text eol=crlf
+*.cmd      text eol=crlf
+*.ps1      text eol=crlf
+
+# Serialisation
+*.json     text
+*.toml     text
+*.xml      text
+*.yaml     text
+*.yml      text
+
+# Archives
+*.7z       binary
+*.gz       binary
+*.tar      binary
+*.tgz      binary
+*.zip      binary
+
+# Text files where line endings should be preserved
+*.patch    -text
+
+#
+# Exclude files from exporting
+#
+
+.gitattributes export-ignore
+.gitignore     export-ignore
+.gitkeep       export-ignore
+
+###
+# https://github.com/gitattributes/gitattributes/blob/master/PHP.gitattributes
+###
+
+# PHP files
+*.php     text eol=lf diff=php
+*.phpt    text eol=lf diff=php
+*.phtml   text eol=lf diff=html
+*.twig    text eol=lf
+*.phar    binary
+
+# Configuration
+phpcs.xml    text eol=lf
+phpunit.xml  text eol=lf
+phpstan.neon text eol=lf
+psalm.xml    text eol=lf
+
+###
+# Open Culture Consulting custom additions
+###
+
+# Configuration
+.editorconfig   text eol=lf
+*.dist.xml      text eol=lf
+*.xml.dist      text eol=lf
+*.neon          text eol=lf
+
+# Generated documentation
+doc/*           linguist-generated=true
+
+# Exclude files from exporting
+.github/*       export-ignore
+.phpdoc/*       export-ignore
+phpdoc.dist.xml export-ignore

.github/dependabot.yml

@@ -4,6 +4,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    versioning-strategy: "increase-if-necessary"
     assignees:
       - "sebastian-meyer"
     labels: [ ]

.github/workflows/phpcs.yml

@@ -0,0 +1,35 @@
+name: PHP Code Sniffer
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  PHPCS:
+    name: PHPCS Scanner
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v4
+
+      - name: Setup Environment
+        uses: php-actions/composer@v6
+        with:
+          command: update
+          php_version: "8.1"
+
+      - name: Run PHPCS
+        uses: php-actions/phpcs@v1
+        with:
+          php_version: "8.1"
+          path: src/
+          standard: phpcs.xml.dist

.github/workflows/phpmd.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Setup Environment
         uses: shivammathur/setup-php@v2
         with:
-          php-version: "8.0"
+          php-version: "8.1"
           coverage: none
           tools: phpmd
 

.github/workflows/phpstan.yml

@@ -26,7 +26,7 @@ jobs:
         uses: php-actions/composer@v6
         with:
           command: update
-          php_version: "8.0"
+          php_version: "8.1"
 
       - name: Run PHPStan
         uses: php-actions/phpstan@v3

.github/workflows/psalm.yml

@@ -0,0 +1,35 @@
+name: Psalm Static Analyzer
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  Psalm:
+    name: Psalm Scanner
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      actions: read
+
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v4
+
+      - name: Run Psalm
+        uses: docker://ghcr.io/psalm/psalm-github-actions
+        with:
+          security_analysis: true
+          report_file: psalm-results.sarif
+
+      - name: Upload Analysis Results
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: psalm-results.sarif
+          wait-for-processing: true

.gitignore

@@ -1,5 +1,10 @@
+/.phpdoc/cache/
 /.vscode/
 /vendor/
 .php-cs-fixer.php
 composer.lock
+phpcs.xml
+phpdoc.xml
 phpstan.neon
+psalm.xml
+TODO

.php-cs-fixer.dist.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * Queue-based PSR-15 HTTP Server Request Handler
- * Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
+ * PHP Basics
+ * Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -11,11 +11,11 @@
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
 declare(strict_types=1);
@@ -24,15 +24,15 @@ namespace PhpCsFixer;
 
 /**
  * Configuration for PHP-CS-Fixer.
+ *
  * @see https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/config.rst
  *
  * @return ConfigInterface
  */
-return (new Config())
+$config = new Config();
+$finder = new Finder();
+
+return $config
     ->setRiskyAllowed(true)
-    ->setRules([
-        '@PSR12' => true,
-    ])
-    ->setFinder(
-        (new Finder())->in(__DIR__)
-    );
+    ->setRules(['@PSR12' => true])
+    ->setFinder($finder->in([__DIR__ . '/src']));

composer.json

@@ -8,6 +8,7 @@
         "request",
         "handler",
         "middleware",
+        "queue",
         "http-server-handler",
         "http-server-middleware"
     ],
@@ -25,19 +26,21 @@
     "support": {
         "issues": "https://github.com/opencultureconsulting/psr-15/issues",
         "source": "https://github.com/opencultureconsulting/psr-15",
-        "docs": "https://github.com/opencultureconsulting/psr-15/blob/main/README.md"
+        "docs": "https://opencultureconsulting.github.io/psr-15/"
     },
     "require": {
-        "php": "^8.0",
+        "php": "^8.1",
         "guzzlehttp/psr7": "^2.6",
-        "opencultureconsulting/basics": "^1.1",
+        "opencultureconsulting/basics": "^2.0",
         "psr/http-server-handler": "^1.0",
         "psr/http-server-middleware": "^1.0"
     },
     "require-dev": {
         "phpstan/phpstan": "^1.10",
         "phpstan/phpstan-strict-rules": "^1.5",
-        "friendsofphp/php-cs-fixer": "^3.48"
+        "friendsofphp/php-cs-fixer": "^3.52",
+        "squizlabs/php_codesniffer": "^3.9",
+        "vimeo/psalm": "^5.23"
     },
     "provide": {
         "psr/http-server-handler-implementation": "1.0",

phpcs.xml.dist

@@ -0,0 +1,10 @@
+<?xml version="1.0"?>
+<ruleset name="OCC Standard Ruleset">
+    <description>Open Culture Consulting strictly follows PSR standards.</description>
+    <file>./src</file>
+    <arg name="extensions" value="php"/>
+    <rule ref="PSR12">
+        <exclude name="PSR2.Classes.PropertyDeclaration.Underscore"/>
+        <exclude name="PSR2.Methods.MethodDeclaration.Underscore"/>
+    </rule>
+</ruleset>

phpdoc.dist.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+    configVersion="3"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://www.phpdoc.org"
+    xsi:schemaLocation="https://www.phpdoc.org https://raw.githubusercontent.com/phpDocumentor/phpDocumentor/master/data/xsd/phpdoc.xsd">
+    <title>PSR-15 Queue</title>
+    <paths>
+        <output>doc</output>
+        <cache>.phpdoc/cache</cache>
+    </paths>
+    <version number="latest">
+        <api format="php">
+            <source dsn=".">
+                <path>/src</path>
+            </source>
+            <extensions>
+                <extension>php</extension>
+            </extensions>
+            <default-package-name>PSR15</default-package-name>
+            <include-source>true</include-source>
+            <ignore-tags>
+                <ignore-tag>extends</ignore-tag>
+                <ignore-tag>implements</ignore-tag>
+                <ignore-tag>phpstan-require-implements</ignore-tag>
+                <ignore-tag>psalm-suppress</ignore-tag>
+            </ignore-tags>
+        </api>
+        <guide format="rst">
+            <source dsn=".">
+                <path>/.phpdoc/guide</path>
+            </source>
+            <output>guides</output>
+        </guide>
+    </version>
+    <setting name="graphs.enabled" value="false"/>
+    <setting name="guides.enabled" value="true"/>
+    <setting name="template.color" value="orange"/>
+</phpdocumentor>

psalm.xml.dist

@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<psalm
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    errorLevel="1"
+    resolveFromConfigFile="true"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="true"
+    findUnusedVariablesAndParams="true"
+>
+    <issueHandlers>
+        <RedundantCastGivenDocblockType errorLevel="suppress"/>
+        <RedundantConditionGivenDocblockType errorLevel="suppress"/>
+        <RedundantFunctionCallGivenDocblockType errorLevel="suppress"/>
+    </issueHandlers>
+    <projectFiles>
+        <directory name="src"/>
+        <ignoreFiles>
+            <directory name="vendor"/>
+        </ignoreFiles>
+    </projectFiles>
+</psalm>

src/AbstractMiddleware.php

@@ -22,34 +22,39 @@ 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 opencultureconsulting/psr15
+ * @package PSR15
  */
 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);
     }

src/MiddlewareQueue.php

@@ -24,15 +24,17 @@ 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.
  *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
- * @package opencultureconsulting/psr15
+ * @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);
     }
 }

src/QueueRequestHandler.php

@@ -24,50 +24,74 @@ 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.
  *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
- * @package opencultureconsulting/psr15
+ * @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);
     }