New separate Bridge facade.

- Bridge helps encapsulate Middleware to Pipe logic and provides fluent interface as well as type safety for arguments passed to pipeline.
- Removed previous `PipelineBridge` class.
- Updated readme.

Author: hsehszroc

.gitignore

@@ -9,4 +9,5 @@
 !phpcs.xml.dist
 !phpstan.dist.neon
 !/Src
+!/Server
 !/Tests/

README.md

@@ -22,7 +22,7 @@ $ composer require thewebsolver/pipeline
 
 	> Use _`Pipeline::sealWith()`_ method to pass a closure to handle thrown exception.
 
-- Provides [bridge][b] for PHP Projects that implements [PSR-7][7], [PSR-15][15] (optional [PSR-11][11]) standards.
+- Provides [bridge][b] for PHP Projects that implements [PSR-7][7] & [PSR-15][15] standards.
 
 	> Use [Queue based Request Handler][q] implementation to handle stacked middlewares inside [Request Handler][h]'s handle method (_`RequestHandlerInterface::handle()`_).
 
@@ -33,7 +33,7 @@ For usage details, visit [Wiki page][w].
 [h]: https://www.php-fig.org/psr/psr-15/#21-psrhttpserverrequesthandlerinterface
 [q]: https://www.php-fig.org/psr/psr-15/meta/#queue-based-request-handler
 [w]: https://github.com/TheWebSolver/pipeline/wiki
-[b]: Src/PipelineBridge.php
+[b]: Server/Bridge.php
 [7]: https://www.php-fig.org/psr/psr-7/
 [15]: https://www.php-fig.org/psr/psr-15/
 [11]: https://www.php-fig.org/psr/psr-11/

Server/Bridge.php

@@ -0,0 +1,90 @@
+<?php // phpcs:disable Squiz.Commenting.FunctionComment.ParamNameNoMatch
+declare( strict_types = 1 );
+
+namespace TheWebSolver\Codegarage\Pipeline\Server;
+
+use Closure;
+use LogicException;
+use Psr\Container\ContainerInterface;
+use TheWebSolver\Codegarage\Lib\Pipe;
+use Psr\Http\Server\MiddlewareInterface;
+use TheWebSolver\Codegarage\Lib\Pipeline;
+use TheWebSolver\Codegarage\Lib\Psr\Middleware;
+use TheWebSolver\Codegarage\Lib\Error\InvalidPipe;
+use Psr\Http\Message\ResponseInterface as Response;
+use TheWebSolver\Codegarage\Lib\Psr\RequestHandler;
+use TheWebSolver\Codegarage\Lib\Error\InvalidPipeline;
+use Psr\Http\Message\ServerRequestInterface as Request;
+use Psr\Http\Server\RequestHandlerInterface as Handler;
+use TheWebSolver\Codegarage\Lib\Interfaces\PipeInterface;
+use TheWebSolver\Codegarage\Lib\Interfaces\ChainOfResponsibility;
+
+class Bridge {
+	/** @var PipeInterface[] */
+	private array $pipes;
+	private Request $request;
+	private Response $response;
+
+	/** @param class-string<Handler> $requestHandlerClassName Accepts a Response instance via constructor. */
+	// phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
+	public function __construct(
+		private readonly ?ContainerInterface $container = null,
+		private readonly ?ChainOfResponsibility $pipeline = null,
+		private readonly string $requestHandlerClassName = RequestHandler::class
+	) {}
+
+	public function for( Request $request, Response $response ): self {
+		$this->request  = $request;
+		$this->response = $response;
+
+		return $this;
+	}
+
+	/**
+	 * @param string|PipeInterface|(Closure(Response, Closure $next, Request, ?string $requestHandlerClassName): Response) $pipe
+	 * @param string|PipeInterface|(Closure(Response, Closure $next, Request, ?string $requestHandlerClassName): Response) ...$pipes
+	 */
+	public function through( string|Closure|PipeInterface $pipe, string|Closure|PipeInterface ...$pipes ): self {
+		foreach ( array( $pipe, ...$pipes ) as $handler ) {
+			$this->pipes[] = Pipe::create( $handler, $this->container );
+		}
+
+		return $this;
+	}
+
+	/**
+	 * @param string|MiddlewareInterface|(Closure(Request, Handler): Response) $middleware
+	 * @param string|MiddlewareInterface|(Closure(Request, Handler): Response) ...$middlewares
+	 */
+	public function throughMiddlewares(
+		string|Closure|MiddlewareInterface $middleware,
+		string|Closure|MiddlewareInterface ...$middlewares
+	): self {
+		foreach ( array( $middleware, ...$middlewares ) as $handler ) {
+			$this->pipes[] = Middleware::toPipe( $handler, $this->container );
+		}
+
+		return $this;
+	}
+
+	/**
+	 * @throws InvalidPipe|InvalidPipeline When Pipe is invalid or other error occurs in the pipeline.
+	 * @throws LogicException              When pipeline does not return a Response instance.
+	 */
+	//  phpcs:ignore Squiz.Commenting.FunctionCommentThrowTag.WrongNumber -- Exact number is vague.
+	public function get(): Response {
+		$transformed = ( $this->pipeline ?? new Pipeline( $this->container ) )
+			->use( $this->request, $this->requestHandlerClassName )
+			->send( $this->response )
+			->through( $this->pipes )
+			->thenReturn();
+
+		// Transformed value is always a Response. Making static analysis happy
+		// and enforcing maximum security of the application along the way.
+		return $transformed instanceof Response
+			? $transformed
+			: throw new LogicException(
+				'Response instance must be returned. Instead returns: ' . get_debug_type( $transformed )
+			);
+	}
+}

Src/Pipeline.php

@@ -21,10 +21,6 @@ final class Pipeline implements ChainOfResponsibility {
 
 	public function __construct( private readonly ?ContainerInterface $container = null ) {}
 
-	public static function withRequest( \Psr\Http\Message\ServerRequestInterface $request ): PipelineBridge {
-		return ( new PipelineBridge() )->withRequest( $request );
-	}
-
 	public static function normalizeException( Throwable $thrown, mixed $subject = null ): InvalidPipe|InvalidPipeline {
 		return $thrown instanceof InvalidPipe ? $thrown : new InvalidPipeline( $thrown, $subject );
 	}

Src/PipelineBridge.php

@@ -14,8 +14,8 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 use Psr\Container\ContainerExceptionInterface;
-use TheWebSolver\Codegarage\Lib\PipelineBridge;
 use TheWebSolver\Codegarage\Lib\Psr\Middleware;
+use TheWebSolver\Codegarage\Pipeline\Server\Bridge;
 use TheWebSolver\Codegarage\Test\Stub\ResponseStub;
 use TheWebSolver\Codegarage\Test\Stub\MiddlewareStub;
 use TheWebSolver\Codegarage\Lib\Interfaces\PipeInterface;
@@ -92,7 +92,7 @@ public function testMiddlewareConversionWithoutContainer( mixed $middleware, ?st
 
 	/** @dataProvider provideMiddlewares */
 	public function testMiddlewareToPipeConversion( mixed $middleware, ?string $thrown = null ): void {
-		$this->assertInstanceOf( PipeInterface::class, PipelineBridge::middlewareToPipe( $middleware ) );
+		$this->assertInstanceOf( PipeInterface::class, Middleware::toPipe( $middleware ) );
 	}
 
 	/** @return array<mixed[]>*/
@@ -136,12 +136,12 @@ public function testPipelineBridgeWithPsr() {
 		/** @var ServerRequestInterface */
 		$request  = $this->createStub( ServerRequestInterface::class );
 		$response = ( new ResponseStub() )->withStatus( 100 );
-		$pipes    = array_map( PipelineBridge::middlewareToPipe( ... ), $this->getRequestHandlerMiddlewares() );
+		$pipes    = array_map( Middleware::toPipe( ... ), $this->getRequestHandlerMiddlewares() );
 		$handler  = new RequestHandlerStub( ( new Pipeline() )->use( $request )->send( $response )->through( $pipes ) );
 
 		$this->assertSame( expected: 500, actual: $handler->handle( $request )->getStatusCode() );
 
-		$handler = new RequestHandlerStub( Pipeline::withRequest( $request )->process( $response )->through( $pipes ) );
+		$handler = new RequestHandlerStub( ( new Bridge() )->for( $request, $response )->through( ...$pipes ) );
 
 		$this->assertSame( expected: 500, actual: $handler->handle( $request )->getStatusCode() );
 	}
@@ -154,8 +154,11 @@ public function __construct( private ResponseInterface $response ) {}
 
 		$this->expectException( LogicException::class );
 
-		( new PipelineBridge() )
-			->middlewareToPipe( new MiddlewareStub() )
-			->handle( $response, $this->fail( ... ), $this->createStub( ServerRequestInterface::class ), $handler::class );
+		Middleware::toPipe( new MiddlewareStub() )->handle(
+			$response,
+			$this->fail( ... ),
+			$this->createStub( ServerRequestInterface::class ),
+			$handler::class
+		);
 	}
 }

Tests/BridgeTest.php

@@ -4,18 +4,16 @@
 namespace TheWebSolver\Codegarage\Test\Stub;
 
 use Psr\Http\Message\ResponseInterface;
+use TheWebSolver\Codegarage\Lib\Pipeline;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\RequestHandlerInterface;
-use TheWebSolver\Codegarage\Lib\PipelineBridge;
+use TheWebSolver\Codegarage\Pipeline\Server\Bridge;
 use TheWebSolver\Codegarage\Lib\Interfaces\ChainOfResponsibility;
 
 class RequestHandlerStub implements RequestHandlerInterface {
-	public function __construct(
-		private readonly ChainOfResponsibility|PipelineBridge $handler,
-		private readonly PipelineBridge $bridge = new PipelineBridge()
-	) {}
+	public function __construct( private readonly ChainOfResponsibility|Bridge $handler ) {}
 
 	public function handle( ServerRequestInterface $request ): ResponseInterface {
-		return $this->handler instanceof PipelineBridge ? $this->handler->getResponse() : $this->handler->thenReturn();
+		return $this->handler instanceof Pipeline ? $this->handler->thenReturn() : $this->handler->get();
 	}
 }

Tests/Stub/RequestHandlerStub.php

@@ -20,7 +20,8 @@
   },
   "autoload": {
     "psr-4": {
-      "TheWebSolver\\Codegarage\\Lib\\": "Src/"
+      "TheWebSolver\\Codegarage\\Lib\\": "Src/",
+      "TheWebSolver\\Codegarage\\Pipeline\\Server\\": "Server/"
     }
   },
   "autoload-dev": {

composer.json

@@ -2,3 +2,4 @@ parameters:
 	level: max
 	paths:
 		- Src
+		- Server