PSR-7, PSR-11, and PSR-15 integration.

Author: hsehszroc

.gitignore

@@ -6,5 +6,7 @@
 !phpunit.xml.dist
 !LICENSE
 !/*.md
+!phpcs.xml.dist
+!phpstan.dist.neon
 !/Src
 !/Tests/

Src/Interfaces/ChainOfResponsibility.php

@@ -0,0 +1,66 @@
+<?php // phpcs:disable Squiz.Commenting.FunctionComment.ParamNameNoMatch, Squiz.Commenting.FunctionComment.IncorrectTypeHint
+declare(strict_types = 1);
+
+namespace TheWebSolver\Codegarage\Lib\Interfaces;
+
+use Closure;
+use Throwable;
+use TheWebSolver\Codegarage\Lib\InvalidPipe;
+use TheWebSolver\Codegarage\Lib\InvalidPipeline;
+use TheWebSolver\Codegarage\Lib\PipeInterface as Handler;
+
+interface ChainOfResponsibility {
+	/**
+	 * Provides additional arguments that can be used by all registered pipes.
+	 */
+	public function use( mixed ...$globalArgsForEachPipe ): static;
+
+	/**
+	 * Provides subject to be transformed by all registered pipes.
+	 */
+	public function send( mixed $subject ): static;
+
+	/**
+	 * Registers a single pipe to transform the subject.
+	 *
+	 * Pipes registered using this method before `ChainOfResponsibility::through()` method
+	 * must be deferred and must transform the subject only after pipes registered using
+	 * `ChainOfResponsibility::through()` method has transformed the subject, if any.
+	 *
+	 * @param class-string<Handler>|Handler|Closure(mixed $subject, Closure $next, mixed ...$args): mixed $handler
+	 */
+	public function pipe( string|Closure|Handler $handler ): static;
+
+	/**
+	 * Registers pipes to transform the subject.
+	 *
+	 * Subject must be transformed in the same order pipes are registered.
+	 *
+	 * @param array<class-string<Handler>|Handler|Closure(mixed $subject, Closure $next, mixed ...$args): mixed> $pipes
+	 */
+	public function through( array $pipes ): static;
+
+	/**
+	 * Catches any exception thrown during transformation of subject and returns the fallback value.
+	 *
+	 * @param Closure(Throwable $exception, mixed ...$args): mixed $fallback
+	 */
+	public function sealWith( Closure $fallback ): static;
+
+	/**
+	 * Returns the transformed subject after passing through all registered pipes and current pipe handle.
+	 *
+	 * @param Closure(mixed $subject, mixed ...$args): mixed $handle
+	 * @throws InvalidPipe            When pipe type could not be resolved.
+	 * @throws InvalidPipeline When a pipe abrupt the pipeline by throwing an exception & sealWith not used.
+	 */
+	public function then( Closure $handle ): mixed;
+
+	/**
+	 * Returns the transformed subject after passing through all registered pipes.
+	 *
+	 * @throws InvalidPipe     When pipe type could not be resolved.
+	 * @throws InvalidPipeline When a pipe abrupt the pipeline by throwing an exception & sealWith not used.
+	 */
+	public function thenReturn(): mixed;
+}

Src/InvalidMiddlewareForPipe.php

@@ -1,10 +1,4 @@
 <?php
-/**
- * Middleware type invalid exception.
- *
- * @package TheWebSolver\Codegarage\Library
- */
-
 declare( strict_types = 1 );
 
 namespace TheWebSolver\Codegarage\Lib;

Src/InvalidPipe.php

@@ -1,10 +1,4 @@
 <?php
-/**
- * Exception when invalid pipe given.
- *
- * @package TheWebSolver\Codegarage\Library
- */
-
 declare( strict_types = 1 );
 
 namespace TheWebSolver\Codegarage\Lib;
@@ -18,8 +12,10 @@ public static function from( mixed $pipe ): self {
 
 	private function __construct( mixed $pipe ) {
 		parent::__construct(
-			message: ! is_string( $pipe ) ? '' : "Invalid pipe classname given: {$pipe}.",
-			code: 400
+			code: 400,
+			message: ! is_string( $pipe )
+				? 'Invalid pipe given: ' . get_debug_type( $pipe )
+				: "Invalid pipe classname given: {$pipe}.",
 		);
 	}
 }

Src/InvalidPipeline.php

@@ -1,9 +1,5 @@
 <?php
-/**
- * Unknown pipeline exception.
- *
- * @package TheWebSolver\Codegarage\Library
- */
+declare( strict_types = 1 );
 
 namespace TheWebSolver\Codegarage\Lib;
 

Src/Pipe.php

@@ -0,0 +1,36 @@
+<?php
+declare( strict_types = 1 );
+
+namespace TheWebSolver\Codegarage\Lib;
+
+use Closure;
+use Throwable;
+use Psr\Container\ContainerInterface;
+
+class Pipe implements PipeInterface {
+	/** @param Closure(mixed $subject, Closure $next, mixed ...$args): mixed $handler */
+	// phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
+	public function __construct( private readonly Closure $handler ) {}
+
+	public function handle( mixed $subject, Closure $next, mixed ...$args ): mixed {
+		return ( $this->handler )( $subject, $next, ...$args );
+	}
+
+	public static function create(
+		string|Closure|PipeInterface $handler,
+		?ContainerInterface $container = null
+	): PipeInterface {
+		try {
+			$pipe = ! is_string( $handler ) ? $handler : ( $container?->get( $handler ) ?? new $handler() );
+
+			return match ( true ) {
+				$pipe instanceof self          => $pipe,
+				$pipe instanceof PipeInterface => new self( $pipe->handle( ... ) ),
+				$pipe instanceof Closure       => new self( $pipe ),
+				default                        => throw InvalidPipe::from( $handler ),
+			};
+		} catch ( Throwable $thrown ) {
+			throw Pipeline::normalizeException( $thrown );
+		}
+	}
+}

Src/PipeInterface.php

@@ -1,25 +1,20 @@
 <?php
-/**
- * The pipeline handler to handle given subject/request.
- *
- * @package TheWebSolver\Codegarage\Library
- */
-
 declare( strict_types = 1 );
 
 namespace TheWebSolver\Codegarage\Lib;
 
 use Closure;
 
 interface PipeInterface {
+	// phpcs:disable Squiz.Commenting.FunctionComment.ParamNameNoMatch
 	/**
 	 * Handles the given subject and returns the transformed data.
 	 *
 	 * @param mixed         $subject The subject to be transformed by the pipe.
-	 * @param Closure(mixed $subject, mixed ...$use): mixed $next
-	 * @param mixed         ...$use  The global args that may or may not be in use
+	 * @param Closure(mixed $subject, mixed ...$args): mixed $next
+	 * @param mixed         ...$args  The global args that may or may not be in use
 	 *                               for the current pipeline.
-	 * @since 1.0
 	 */
-	public function handle( mixed $subject, Closure $next, mixed ...$use ): mixed;
+	// phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
+	public function handle( mixed $subject, Closure $next, mixed ...$args ): mixed;
 }

Src/PipeResponseHandler.php

@@ -1,19 +1,13 @@
 <?php
-/**
- * Server Request Handler that returns the middleware response hydrated by the pipe.
- *
- * @package TheWebSolver\Codegarage\Library
- */
-
 declare( strict_types = 1 );
 
-namespace TheWebSolver\Codegarage\Lib;
+namespace TheWebSolver\Codegarage\Lib\Psr;
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
-class PipeResponseHandler implements RequestHandlerInterface {
+class RequestHandler implements RequestHandlerInterface {
 	public function __construct( private readonly ResponseInterface $response ) {}
 
 	public function handle( ServerRequestInterface $request ): ResponseInterface {