diff --git a/src/Dispatching/DispatchStackInterface.php b/src/Dispatching/DispatchStackInterface.php index 53182f4..953281c 100644 --- a/src/Dispatching/DispatchStackInterface.php +++ b/src/Dispatching/DispatchStackInterface.php @@ -7,14 +7,14 @@ use Psr\Http\Message\ServerRequestInterface; use WellRESTed\MiddlewareInterface; /** - * Dispatches an ordered sequence of middleware. + * Dispatches an ordered sequence of middleware */ interface DispatchStackInterface extends MiddlewareInterface { /** * Push a new middleware onto the stack. * - * This method MUST preserve the order in which middleware added. + * This method MUST preserve the order in which middleware are added. * * @param mixed $middleware Middleware to dispatch in sequence * @return self @@ -31,9 +31,9 @@ interface DispatchStackInterface extends MiddlewareInterface * middleware. The last middleware MUST receive a $next callable that * returns the response unchanged. * - * When any middleware does not call the $next argument it recieved, the - * stack instance MUST stop propogating through the stack and MUST return - * the response without calling the $next argument passed to dispatch. + * When any middleware returns a response without calling the $next + * argument it recieved, the stack instance MUST stop propogating and MUST + * return a response without calling the $next argument passed to __invoke. * * This method MUST call the passed $next argument when: * - The stack is empty (i.e., there is no middleware to dispatch) diff --git a/src/Dispatching/DispatcherInterface.php b/src/Dispatching/DispatcherInterface.php index f98e2a1..f1fe1f7 100644 --- a/src/Dispatching/DispatcherInterface.php +++ b/src/Dispatching/DispatcherInterface.php @@ -5,6 +5,9 @@ namespace WellRESTed\Dispatching; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; +/** + * Dispatches middleware + */ interface DispatcherInterface { /** @@ -22,11 +25,11 @@ interface DispatcherInterface * - 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::dispatch + * - A callable with a signature matching MiddlewareInterface::__invoke * * Implementation MAY dispatch other types of middleware. * - * When an implementation recieves a $middware that is not of a type it can + * When an implementation receives a $middware that is not of a type it can * dispatch, it MUST throw a DispatchException. * * @param mixed $middleware diff --git a/src/MiddlewareInterface.php b/src/MiddlewareInterface.php index a7ccb25..b56407b 100644 --- a/src/MiddlewareInterface.php +++ b/src/MiddlewareInterface.php @@ -8,6 +8,27 @@ use Psr\Http\Message\ServerRequestInterface; interface MiddlewareInterface { /** + * Accepts a request and response and returns a modified response. + * + * $request represents the request issued by the client. + * + * $response represents the current state of the response. + * + * $next is a callable that expects a request and response as parameters + * and returns a response. Calling $next forwards a request and response + * to the next middleware in the sequence (if any) and continues + * propagation; returning a response without calling $next halts propgation + * and prevents subsequent middleware from running. + * + * Implementations MAY call $next to continue propagation. After calling + * $next, implementations MUST return the response returned by $next or + * use $next's returned response to determine the response it will + * ulitimately return. Implementations MUST NOT call $next and disregard + * $next's returned response. + * + * Implementaitons MAY return a response without calling $next to halt + * propagation. + * * @param ServerRequestInterface $request * @param ResponseInterface $response * @param callable $next diff --git a/src/Routing/MethodMapInterface.php b/src/Routing/MethodMapInterface.php index 3daef77..df92364 100644 --- a/src/Routing/MethodMapInterface.php +++ b/src/Routing/MethodMapInterface.php @@ -2,10 +2,28 @@ namespace WellRESTed\Routing; +use Psr\Http\Message\ResponseInterface; +use Psr\Http\Message\ServerRequestInterface; use WellRESTed\MiddlewareInterface; +/** + * Maps HTTP methods to middleware + */ interface MethodMapInterface extends MiddlewareInterface { + /** + * Evaluate $request's method and dispatches matching middleware. + * + * Implementations MUST pass $request, $response, and $next to the matching + * middleware. + * + * @param ServerRequestInterface $request + * @param ResponseInterface $response + * @param callable $next + * @return ResponseInterface + */ + public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next); + /** * Register middleware with a method. * @@ -22,9 +40,6 @@ interface MethodMapInterface extends MiddlewareInterface * - A callable maching the signature of MiddlewareInteraface::dispatch * @see DispatcherInterface::dispatch * - * $middleware may also be null, in which case any previously set - * middleware for that method or methods will be unset. - * * @param string $method * @param mixed $middleware */ diff --git a/src/Routing/Route/RouteFactoryInterface.php b/src/Routing/Route/RouteFactoryInterface.php index 87301ff..9abe5a6 100644 --- a/src/Routing/Route/RouteFactoryInterface.php +++ b/src/Routing/Route/RouteFactoryInterface.php @@ -7,9 +7,9 @@ interface RouteFactoryInterface /** * Creates a route for the given target. * - * - Target with no special characters will create StaticRoutes - * - Target ending with * will create PrefixRoutes - * - Target containing URI variables (e.g., {id}) will create TemplateRoutes + * - Targets with no special characters will create StaticRoutes + * - Targets ending with * will create PrefixRoutes + * - Targets containing URI variables (e.g., {id}) will create TemplateRoutes * - Regular exressions will create RegexRoutes * * @param string $target Route target or target pattern diff --git a/src/Routing/Route/RouteInterface.php b/src/Routing/Route/RouteInterface.php index 59fb98f..ad8a917 100644 --- a/src/Routing/Route/RouteInterface.php +++ b/src/Routing/Route/RouteInterface.php @@ -39,7 +39,7 @@ interface RouteInterface extends MiddlewareInterface /** * Return an array of variables extracted from the path most recently - * passed to matchesRequestTarget. + * passed to matchesRequestTarget. * * If the path does not contain variables, or if matchesRequestTarget * has not yet been called, this method MUST return an empty array. diff --git a/src/Routing/Router.php b/src/Routing/Router.php index 9ebf8e3..8e93688 100644 --- a/src/Routing/Router.php +++ b/src/Routing/Router.php @@ -4,7 +4,6 @@ namespace WellRESTed\Routing; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; -use WellRESTed\Dispatching\Dispatcher; use WellRESTed\Dispatching\DispatcherInterface; use WellRESTed\Routing\Route\RouteFactory; use WellRESTed\Routing\Route\RouteFactoryInterface; diff --git a/src/Routing/RouterInterface.php b/src/Routing/RouterInterface.php index aba7c80..018045e 100644 --- a/src/Routing/RouterInterface.php +++ b/src/Routing/RouterInterface.php @@ -2,23 +2,41 @@ namespace WellRESTed\Routing; +use Psr\Http\Message\ResponseInterface; +use Psr\Http\Message\ServerRequestInterface; use WellRESTed\MiddlewareInterface; +/** + * Maps HTTP methods and paths to middleware + */ interface RouterInterface extends MiddlewareInterface { + /** + * Evaluate $request's path and method and dispatches matching middleware. + * + * Implementations MUST pass $request, $response, and $next to the matching + * middleware. + * + * @param ServerRequestInterface $request + * @param ResponseInterface $response + * @param callable $next + * @return ResponseInterface + */ + public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next); + /** * Register middleware with the router for a given path and method. * * $method may be: - * - A single verb ("GET"), + * - A single verb ("GET") * - A comma-separated list of verbs ("GET,PUT,DELETE") - * - "*" to indicate any method. + * - "*" to indicate any method * @see MethodMapInterface::register * * $target may be: * - An exact path (e.g., "/path/") - * - An prefix path ending with "*"" ("/path/*"") - * - A URI template with variables enclosed in "{}" ("/path/{id}") + * - A prefix path ending with "*"" ("/path/*"") + * - A URI template with one or more variables ("/path/{id}") * - A regular expression ("~/cat/([0-9]+)~") * * $middleware may be: