Improve dispatcher error messages

phpstan.neon

@@ -19,6 +19,10 @@ parameters:
 		- '#^Return typehint of method Apitte\\Core\\Http\\ApiResponse::getEntity\(\) has invalid type Apitte\\Negotiation\\Http\\AbstractEntity.$#'
 		- '#^Parameter \$entity of method Apitte\\Core\\Http\\ApiResponse::withEntity\(\) has invalid typehint type Apitte\\Negotiation\\Http\\AbstractEntity.$#'
 		- '#^Call to static method from\(\) on an unknown class Apitte\\Negotiation\\Http\\#'
+		- '#^Class Apitte\\Negotiation\\Http\\ArrayEntity not found.$#'
 
 		# Maybe will cause application fail - DecoratorManager::decorateResponse could return null, but DecoratedDispatcher is not always able to handle it.
 		- '#Method Apitte\\Core\\Dispatcher\\DecoratedDispatcher::handle\(\) should return Psr\\Http\\Message\\ResponseInterface but returns Psr\\Http\\Message\\ResponseInterface|null.#'
+
+		# DecoratedDispatcher
+		- '#Call to an undefined method Psr\\Http\\Message\\ResponseInterface::withEntity\(\)#'

src/Dispatcher/CoreDispatcher.php

@@ -49,7 +49,7 @@ protected function handle(ServerRequestInterface $request, ResponseInterface $re
 
 		// Validate if response is ResponseInterface
 		if (!($response instanceof ResponseInterface)) {
-			throw new InvalidStateException(sprintf('Handler returned response must implement "%s"', ResponseInterface::class));
+			throw new InvalidStateException(sprintf('Endpoint returned response must implement "%s"', ResponseInterface::class));
 		}
 
 		return $response;

src/Dispatcher/DecoratedDispatcher.php

@@ -95,19 +95,15 @@ protected function handle(ServerRequestInterface $request, ResponseInterface $re
 		// if result is scalar convert it manually to ScalarEntity,
 		// if result is IResponseEntity convert it manually to MappingEntity,
 		// otherwise use result as response
-		if (is_array($result)) {
-			$response = $response->withEntity(ArrayEntity::from($result));
-		} elseif (is_scalar($result)) {
-			$response = $response->withEntity(ScalarEntity::from($result));
-		} elseif ($result instanceof IResponseEntity) {
-			$response = $response->withEntity(MappingEntity::from($result));
+		if (is_array($result) || is_scalar($result) || $result instanceof IResponseEntity) {
+			$response = $this->negotiate($result, $response);
 		} else {
-			$response = $result;
-		}
+			// Validate if response is ResponseInterface
+			if (!($result instanceof ResponseInterface)) {
+				throw new InvalidStateException(sprintf('Endpoint returned response must implement "%s"', ResponseInterface::class));
+			}
 
-		// Validate if response is ResponseInterface
-		if (!($response instanceof ResponseInterface)) {
-			throw new InvalidStateException(sprintf('Handler returned response must implement "%s"', ResponseInterface::class));
+			$response = $result;
 		}
 
 		try {
@@ -120,4 +116,28 @@ protected function handle(ServerRequestInterface $request, ResponseInterface $re
 		return $response;
 	}
 
+	/**
+	 * @param mixed $result
+	 * @param ApiResponse|ResponseInterface $response
+	 */
+	protected function negotiate($result, ResponseInterface $response): ApiResponse
+	{
+		if (!class_exists(ArrayEntity::class)) {
+			throw new InvalidStateException(sprintf(
+				'If you want return anything else than "%s" from your api endpoint then install "apitte/negotiation".',
+				ResponseInterface::class
+			));
+		}
+
+		if (is_array($result)) {
+			$response = $response->withEntity(ArrayEntity::from($result));
+		} elseif (is_scalar($result)) {
+			$response = $response->withEntity(ScalarEntity::from($result));
+		} elseif ($result instanceof IResponseEntity) {
+			$response = $response->withEntity(MappingEntity::from($result));
+		}
+
+		return $response;
+	}
+
 }

src/Dispatcher/JsonDispatcher.php

@@ -26,7 +26,7 @@ protected function handle(ServerRequestInterface $request, ResponseInterface $re
 
 		// Validate if response is ResponseInterface
 		if (!($response instanceof ResponseInterface)) {
-			throw new InvalidStateException(sprintf('Handler returned response must implement "%s"', ResponseInterface::class));
+			throw new InvalidStateException(sprintf('Endpoint returned response must implement "%s"', ResponseInterface::class));
 		}
 
 		return $response;

tests/cases/Dispatcher/CoreDispatcher.phpt

@@ -35,7 +35,7 @@ test(function (): void {
 
 	Assert::exception(function () use ($dispatcher, $request, $response): void {
 		$dispatcher->dispatch($request, $response);
-	}, InvalidStateException::class, sprintf('Handler returned response must implement "%s"', ResponseInterface::class));
+	}, InvalidStateException::class, sprintf('Endpoint returned response must implement "%s"', ResponseInterface::class));
 });
 
 // Request not matched, throw exception

tests/cases/Dispatcher/DecoratedDispatcher.phpt

@@ -25,6 +25,7 @@ use Tests\Fixtures\Decorator\ThrowExceptionFromContextResponseDecorator;
 use Tests\Fixtures\Handler\ErroneousHandler;
 use Tests\Fixtures\Handler\FakeNullHandler;
 use Tests\Fixtures\Handler\FakeResponseHandler;
+use Tests\Fixtures\Handler\ReturnFooBarHandler;
 use Tests\Fixtures\Router\FakeRouter;
 
 //TODO - EarlyReturnResponseException
@@ -63,7 +64,19 @@ test(function (): void {
 
 	Assert::exception(function () use ($dispatcher, $request, $response): void {
 		$dispatcher->dispatch($request, $response);
-	}, InvalidStateException::class, sprintf('Handler returned response must implement "%s"', ResponseInterface::class));
+	}, InvalidStateException::class, sprintf('Endpoint returned response must implement "%s"', ResponseInterface::class));
+});
+
+// Match request, use invalid handler, throw exception
+test(function (): void {
+	$request = Psr7ServerRequestFactory::fromSuperGlobal();
+	$response = Psr7ResponseFactory::fromGlobal();
+
+	$dispatcher = new DecoratedDispatcher(new FakeRouter(true), new ReturnFooBarHandler(), new DecoratorManager());
+
+	Assert::exception(function () use ($dispatcher, $request, $response): void {
+		$dispatcher->dispatch($request, $response);
+	}, InvalidStateException::class, sprintf('If you want return anything else than "%s" from your api endpoint then install "apitte/negotiation".', ResponseInterface::class));
 });
 
 // Match request, decorate request, throw exception, return response from exception

tests/cases/Dispatcher/JsonDispatcher.phpt

@@ -47,7 +47,7 @@ test(function (): void {
 	$dispatcher = new JsonDispatcher(new FakeRouter(true), new FakeNullHandler());
 	Assert::exception(function () use ($dispatcher, $request, $response): void {
 		$dispatcher->dispatch($request, $response);
-	}, InvalidStateException::class, sprintf('Handler returned response must implement "%s"', ResponseInterface::class));
+	}, InvalidStateException::class, sprintf('Endpoint returned response must implement "%s"', ResponseInterface::class));
 });
 
 // Not matched, use fallback, write error to response body