Custom exceptions, enhancement & refactoring.

Author: hsehszroc

Src/InvalidMiddlewareForPipeError.php

@@ -0,0 +1,14 @@
+<?php
+/**
+ * Middleware type invalid exception.
+ *
+ * @package TheWebSolver\Codegarage\Library
+ */
+
+declare( strict_types = 1 );
+
+namespace TheWebSolver\Codegarage\Lib;
+
+use TypeError;
+
+class InvalidMiddlewareForPipeError extends TypeError {}

Src/MiddlewarePsrNotFoundException.php

@@ -0,0 +1,14 @@
+<?php
+/**
+ * PSR implementation not found exception.
+ *
+ * @package TheWebSolver\Codegarage\Library
+ */
+
+declare( strict_types = 1 );
+
+namespace TheWebSolver\Codegarage\Lib;
+
+use RuntimeException;
+
+class MiddlewarePsrNotFoundException extends RuntimeException {}

Src/Pipeline.php

@@ -134,7 +134,7 @@ public function sealWith( Closure $fallback ): static {
 	}
 
 	/**
-	 * Appends additional pipes onto the pipeline.
+	 * Appends additional pipes to the pipeline stack.
 	 *
 	 * @param string|Pipe|Closure(mixed $subject, Closure $next, mixed ...$use): mixed
 	 * @phpstan-param class-string<Pipe>|Pipe|Closure(mixed $subject, Closure $next, mixed ...$use): mixed $pipe
@@ -146,10 +146,11 @@ public function pipe( string|Closure|Pipe $pipe ): static {
 	}
 
 	/**
-	 * Runs the provided return pipe after passing through all pipes.
+	 * Gets the transformed subject after passing through one last pipe.
 	 *
 	 * @param Closure(mixed $subject, mixed ...$use): mixed $return
-	 * @throws Throwable When a pipe abrupt the pipeline by throwing an exception & sealWith not used.
+	 * @throws InvalidPipeError            When pipe type could not be resolved.
+	 * @throws UnexpectedPipelineException When a pipe abrupt the pipeline by throwing an exception & sealWith not used.
 	 */
 	public function then( Closure $return ): mixed {
 		$use     = $this->use ?? array();
@@ -159,11 +160,22 @@ public function then( Closure $return ): mixed {
 		try {
 			return array_reduce( $pipes, $this->chain( ... ), $return )( $subject, ...$use );
 		} catch ( Throwable $e ) {
-			return ( $catcher = $this->catcher ?? null ) ? $catcher( $e, ...$use ) : throw $e;
+			if ( $catcher = $this->catcher ?? null ) {
+				return $catcher( $e, ...$use );
+			}
+
+			return $e instanceof InvalidPipeError
+				? throw $e
+				: throw new UnexpectedPipelineException( $e->getMessage(), $e->getCode(), $e );
 		}
 	}
 
-	/** Passes through pipes in the pipeline and returns the transformed result. */
+	/**
+	 * Passes through pipes in the pipeline and returns the transformed result.
+	 *
+	 * @throws InvalidPipeError            When pipe type could not be resolved.
+	 * @throws UnexpectedPipelineException When a pipe abrupt the pipeline by throwing an exception & sealWith not used.
+	 */
 	public function thenReturn() {
 		return $this->then( return: static fn( $transformed ) => $transformed );
 	}

Src/PipelineBridge.php

@@ -11,8 +11,6 @@
 
 use Closure;
 use Throwable;
-use TypeError;
-use LogicException;
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Server\MiddlewareInterface as Middleware;
 use TheWebSolver\Codegarage\Lib\PipeInterface as Pipe;
@@ -50,35 +48,36 @@ public function handle( mixed $subject, Closure $next, mixed ...$use ): mixed {
 	}
 
 	/**
-	 * @throws LogicException When invoked on projects that doesn't implement PSR7 & PSR15.
-	 * @throws TypeError      When middleware creation fails due to invalid classname.
+	 * @throws MiddlewarePsrNotFoundException When invoked on projects that doesn't implement PSR7 & PSR15.
+	 * @throws InvalidMiddlewareForPipeError  When middleware creation fails due to invalid classname.
+	 * @throws UnexpectedPipelineException    When could not determine thrown exception.
 	 */
 	public static function toMiddleware( mixed $middleware ): object {
 		$interface = static::hasMiddlewareInterfaceAdapter()
 			? static::$middlewareInterface
-			: '\\Psr\\Http\\Server\\MiddlewareInterface';
-
-		if ( ! interface_exists( $interface ) ) {
-			throw new LogicException( 'Cannot find implementation of PSR15 HTTP Server Middleware.' );
-		}
+			: (
+				! interface_exists( $default = '\\Psr\\Http\\Server\\MiddlewareInterface' )
+					? throw new MiddlewarePsrNotFoundException( 'Cannot find PSR15 HTTP Server Middleware.' )
+					: $default
+			);
 
 		$provided    = $middleware;
 		$isClassName = is_string( $middleware ) && class_exists( $middleware );
 
 		try {
-			$middleware = ( match ( true ) {
+			$middleware = match ( true ) {
 				// Middleware classname is a non-existing classname, then default to null.
 				default                         => null,
 				$middleware instanceof Closure  => $middleware,
 				$isClassName                    => static::make( $middleware )->process( ... ),
 				is_a( $middleware, $interface ) => $middleware->process( ... ),
-			} );
+			};
 
 			if ( null === $middleware ) {
-				throw new TypeError(
+				throw new InvalidMiddlewareForPipeError(
 					sprintf(
 						'Invalid or Non-existing class "%1$s". Middleware must be a Closure, an'
-						. ' instance of %2$sor classname of a class that implements %2$s.',
+						. ' instance of %2$s or a concrete\'s classname that implements %2$s.',
 						$isClassName ? $provided : $provided::class,
 						$interface
 					)
@@ -87,11 +86,15 @@ public static function toMiddleware( mixed $middleware ): object {
 
 			return static::getMiddlewareAdapter( $middleware );
 		} catch ( Throwable $e ) {
-			if ( $e instanceof TypeError || ! is_string( $middleware ) ) {
+			if ( $e instanceof InvalidMiddlewareForPipeError ) {
 				throw $e;
 			}
 
-			throw new TypeError(
+			if ( ! is_string( $middleware ) ) {
+				throw new UnexpectedPipelineException( $e->getMessage(), $e->getCode(), $e );
+			}
+
+			throw new InvalidMiddlewareForPipeError(
 				sprintf(
 					'The given middleware classname: "%1$s" must be an instance of "%2$s".',
 					$middleware,

Src/UnexpectedPipelineException.php

@@ -0,0 +1,12 @@
+<?php
+/**
+ * Unknown pipeline exception.
+ *
+ * @package TheWebSolver\Codegarage\Library
+ */
+
+namespace TheWebSolver\Codegarage\Lib;
+
+use Exception;
+
+class UnexpectedPipelineException extends Exception {}

Tests/BridgeTest.php

@@ -9,7 +9,6 @@
 
 namespace TheWebSolver\Codegarage\Lib;
 
-use LogicException;
 use MiddlewareAdapter;
 use Psr7Adapter\Request;
 use Psr7Adapter\Response;
@@ -73,8 +72,8 @@ public function process(
 
 		// Must always throw exception if core PSR-15 implementation not used.
 		if ( ! $this->PSRPackageInstalled ) {
-			$this->expectException( LogicException::class );
-			$this->expectExceptionMessage( 'Cannot find implementation of PSR15 HTTP Server Middleware.' );
+			$this->expectException( MiddlewarePsrNotFoundException::class );
+			$this->expectExceptionMessage( 'Cannot find PSR15 HTTP Server Middleware.' );
 
 			PipelineBridge::toMiddleware( middleware: '' );
 		}

Tests/PipelineTest.php

@@ -162,7 +162,7 @@ public function testPipeSealer(): void {
 		);
 
 		// When "Pipeline::sealWith()" is not used, exception is thrown.
-		$this->expectException( RuntimeException::class );
+		$this->expectException( UnexpectedPipelineException::class );
 
 		( new Pipeline() )
 			->send( subject: 'test' )