From b82ebf6d9537bfa8f767ea8239bcaa0384e023b3 Mon Sep 17 00:00:00 2001 From: PJ Dietz Date: Fri, 22 Jun 2018 12:17:30 -0400 Subject: [PATCH] Update comments and documentation for Dispatcher and related classes --- src/Dispatching/DispatchStack.php | 13 +++--- src/Dispatching/DispatchStackInterface.php | 8 +++- src/Dispatching/Dispatcher.php | 24 ++++++++++- src/Dispatching/DispatcherInterface.php | 43 +++++++++++-------- .../unit/Transmission/TransmitterTest.php | 8 +--- 5 files changed, 64 insertions(+), 32 deletions(-) diff --git a/src/Dispatching/DispatchStack.php b/src/Dispatching/DispatchStack.php index c841d0f..76cdc01 100644 --- a/src/Dispatching/DispatchStack.php +++ b/src/Dispatching/DispatchStack.php @@ -54,8 +54,11 @@ class DispatchStack implements DispatchStackInterface * @param callable $next * @return ResponseInterface */ - public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next) - { + public function __invoke( + ServerRequestInterface $request, + ResponseInterface $response, + $next + ) { $dispatcher = $this->dispatcher; // This flag will be set to true when the last middleware calls $next. @@ -70,9 +73,9 @@ class DispatchStack implements DispatchStackInterface // Create a chain of callables. // - // Each callable wil take $request and $response parameters, and will - // contain a dispatcher, the associated middleware, and a $next - // that is the links to the next middleware in the chain. + // Each callable will take $request and $response parameters, and will + // contain a dispatcher, the associated middleware, and a $next function + // that serves as the link to the next middleware in the chain. foreach (array_reverse($this->stack) as $middleware) { $chain = function ($request, $response) use ($dispatcher, $middleware, $chain) { return $dispatcher->dispatch($middleware, $request, $response, $chain); diff --git a/src/Dispatching/DispatchStackInterface.php b/src/Dispatching/DispatchStackInterface.php index 6cffda5..3945c4c 100644 --- a/src/Dispatching/DispatchStackInterface.php +++ b/src/Dispatching/DispatchStackInterface.php @@ -17,7 +17,7 @@ interface DispatchStackInterface extends MiddlewareInterface * This method MUST preserve the order in which middleware are added. * * @param mixed $middleware Middleware to dispatch in sequence - * @return self + * @return static */ public function add($middleware); @@ -48,5 +48,9 @@ interface DispatchStackInterface extends MiddlewareInterface * @param callable $next * @return ResponseInterface */ - public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next); + public function __invoke( + ServerRequestInterface $request, + ResponseInterface $response, + $next + ); } diff --git a/src/Dispatching/Dispatcher.php b/src/Dispatching/Dispatcher.php index 38444fa..5e6a76f 100644 --- a/src/Dispatching/Dispatcher.php +++ b/src/Dispatching/Dispatcher.php @@ -7,9 +7,31 @@ use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\RequestHandlerInterface; +/** + * Dispatches handlers and middleware + */ class Dispatcher implements DispatcherInterface { /** + * Dispatch a handler or middleware and return the response. + * + * Dispatcher can dispatch any of the following: + * - An instance implementing one of these interfaces: + * - Psr\Http\Server\RequestHandlerInterface + * - Psr\Http\Server\MiddlewareInterface + * - WellRESTed\MiddlewareInterface + * - Psr\Http\Message\ResponseInterface + * - A string containing the fully qualified class name of a class + * implementing one of the interfaces listed above. + * - A callable that returns an instance implementing one of the + * interfaces listed above. + * - A callable with a signature matching the signature of + * WellRESTed\MiddlewareInterface::__invoke + * - An array containing any of the items in this list. + * + * When Dispatcher receives a $dispatchable that is not of a type it + * can dispatch, it throws a DispatchException. + * * @param mixed $dispatchable * @param ServerRequestInterface $request * @param ResponseInterface $response @@ -41,7 +63,7 @@ class Dispatcher implements DispatcherInterface } elseif ($dispatchable instanceof ResponseInterface) { return $dispatchable; } else { - throw new DispatchException("Unable to dispatch middleware."); + throw new DispatchException('Unable to dispatch middleware.'); } } diff --git a/src/Dispatching/DispatcherInterface.php b/src/Dispatching/DispatcherInterface.php index 28bd113..7be31af 100644 --- a/src/Dispatching/DispatcherInterface.php +++ b/src/Dispatching/DispatcherInterface.php @@ -6,38 +6,47 @@ use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; /** - * Dispatches middleware + * Dispatches handlers and middleware */ interface DispatcherInterface { /** - * Dispatch middleware and return the response. + * Dispatch a handler or middleware and return the response. * - * This method MUST pass $request, $response, and $next to the middleware - * to be dispatched. - * - * $middleware comes in a number of varieties (e.g., instance, string, - * callable). DispatcherInterface interface exist to unpack the middleware - * and dispatch it. + * Dispatchables (middleware and handlers) comes in a number of varieties + * (e.g., instance, string, callable). DispatcherInterface interface unpacks + * the dispatchable and dispatches it. * * Implementations MUST be able to dispatch the following: - * - An instance implementing MiddlewareInterface - * - A string containing the fully qualified class name of a class - * implementing MiddlewareInterface - * - A callable that returns an instance implementing MiddlewareInterface - * - A callable with a signature matching MiddlewareInterface::__invoke + * - An instance implementing one of these interfaces: + * - Psr\Http\Server\RequestHandlerInterface + * - Psr\Http\Server\MiddlewareInterface + * - WellRESTed\MiddlewareInterface + * - Psr\Http\Message\ResponseInterface + * - A string containing the fully qualified class name of a class + * implementing one of the interfaces listed above. + * - A callable that returns an instance implementing one of the + * interfaces listed above. + * - A callable with a signature matching the signature of + * WellRESTed\MiddlewareInterface::__invoke + * - An array containing any of the items in this list. * * Implementation MAY dispatch other types of middleware. * - * When an implementation receives a $middleware that is not of a type it can - * dispatch, it MUST throw a DispatchException. + * When an implementation receives a $dispatchable that is not of a type it + * can dispatch, it MUST throw a DispatchException. * - * @param mixed $middleware + * @param mixed $dispatchable * @param ServerRequestInterface $request * @param ResponseInterface $response * @param callable $next * @return ResponseInterface * @throws DispatchException Unable to dispatch $middleware */ - public function dispatch($middleware, ServerRequestInterface $request, ResponseInterface $response, $next); + public function dispatch( + $dispatchable, + ServerRequestInterface $request, + ResponseInterface $response, + $next + ); } diff --git a/test/tests/unit/Transmission/TransmitterTest.php b/test/tests/unit/Transmission/TransmitterTest.php index 33b2e3f..2d22689 100644 --- a/test/tests/unit/Transmission/TransmitterTest.php +++ b/test/tests/unit/Transmission/TransmitterTest.php @@ -25,7 +25,7 @@ class TransmitterTest extends TestCase $this->request = (new ServerRequest()) ->withMethod("HEAD"); - $this->body = $this->prophesize('\Psr\Http\Message\StreamInterface'); + $this->body = $this->prophesize(StreamInterface::class); $this->body->isReadable()->willReturn(false); $this->body->getSize()->willReturn(1024); /** @var StreamInterface $stream */ @@ -36,12 +36,6 @@ class TransmitterTest extends TestCase ->withBody($stream); } - public function testCreatesInstance() - { - $transmitter = new Transmitter(); - $this->assertNotNull($transmitter); - } - public function testSendStatusCodeWithReasonPhrase() { $transmitter = new Transmitter();