Applications
In zend-expressive, you define a Zend\Expressive\Application
instance and
execute it. The Application
instance is itself middleware
that composes:
- a router, for dynamically routing requests to middleware.
- a dependency injection container, for retrieving middleware to dispatch.
- a final handler, for handling error conditions raised by the application.
- an emitter, for emitting the response when application execution is complete.
You can define the Application
instance in several ways:
- Direct instantiation, which requires providing several dependencies.
- The
AppFactory
, which will use sane defaults, but allows injecting alternate container and/or router implementations. - Via a dependency injection container; we provide a factory for setting up all aspects of the instance via configuration and other defined services.
Regardless of how you setup the instance, there are several methods you will likely interact with at some point or another.
Instantiation
As noted at the start of this document, we provide several ways to create an
Application
instance.
Constructor
If you wish to manually instantiate the Application
instance, it has the
following constructor:
/**
* @param Zend\Expressive\Router\RouterInterface $router
* @param null|Interop\Container\ContainerInterface $container IoC container from which to pull services, if any.
* @param null|callable $finalHandler Final handler to use when $out is not
* provided on invocation.
* @param null|Zend\Diactoros\Response\EmitterInterface $emitter Emitter to use when `run()` is
* invoked.
*/
public function __construct(
Zend\Expressive\Router\RouterInterface $router,
Interop\Container\ContainerInterface $container = null,
callable $finalHandler = null,
Zend\Diactoros\Response\EmitterInterface $emitter = null
);
If no container is provided at instantiation, then all routed and piped middleware must be provided as callables.
AppFactory
Zend\Expressive\AppFactory
provides a convenience layer for creating an
Application
instance; it makes the assumption that you will use defaults in
most situations, and likely only change which container and/or router you wish
to use. It has the following signature:
AppFactory::create(
Interop\Container\ContainerInterface $container = null,
Zend\Expressive\Router\RouterInterface $router = null
);
When no container or router are provided, it defaults to:
- zend-servicemanager for the container.
- Aura.Router for the router.
Container factory
We also provide a factory that can be consumed by a container-interop dependency injection container; see the container factories documentation for details.
Adding routable middleware
We discuss routing vs piping elsewhere; routing is the act of dynamically matching an incoming request against criteria, and it is one of the primary features of zend-expressive.
Regardless of which router implementation you use, you can use the following methods to provide routable middleware:
route()
route()
has the following signature:
public function route(
$pathOrRoute,
$middleware = null,
array $methods = null,
$name = null
) : Zend\Expressive\Router\Route
where:
$pathOrRoute
may be either a string path to match, or aZend\Expressive\Router\Route
instance.$middleware
must be present if$pathOrRoute
is a string path, and must be a callable or a service name that resolves to valid middleware.$methods
must be an array of HTTP methods valid for the given path and middleware. If null, it assumes any method is valid.$name
is the optional name for the route, and is used when generating a URI from known routes. See the section on route naming for details.
This method is typically only used if you want a single middleware to handle multiple HTTP request methods.
get(), post(), put(), patch(), delete(), any()
Each of the methods get()
, post()
, put()
, patch()
, delete()
, and any()
proxies to route()
and has the signature:
function (
$pathOrRoute,
$middleware = null,
$name = null
) : Zend\Expressive\Router\Route
Essentially, each calls route()
and specifies an array consisting solely of
the corresponding HTTP method for the $methods
argument.
Piping
Because zend-expressive builds on zend-stratigility,
and, more specifically, its MiddlewarePipe
definition, you can also pipe
(queue) middleware to the application. This is useful for adding middleware that
should execute on each request, defining error handlers, and/or segregating
applications by subpath.
The signature of pipe()
is:
public function pipe($pathOrMiddleware, $middleware = null)
where:
$pathOrMiddleware
is either a string URI path (for path segregation), a callable middleware, or the service name for a middleware to fetch from the composed container.$middleware
is required if$pathOrMiddleware
is a string URI path. It can be either a callable, or the service name for a middleware to fetch from the composed container.
Unlike Zend\Stratigility\MiddlewarePipe
, Application::pipe()
allows
fetching middleware by service name. This facility allows lazy-loading of
middleware only when it is invoked. Internally, it wraps the call to fetch and
dispatch the middleware inside a closure.
Additionally, we define a new method, pipeErrorHandler()
, with the following
signature:
public function pipeErrorHandler($pathOrMiddleware, $middleware = null)
It acts just like pipe()
except when the middleware specified is a service
name; in that particular case, when it wraps the middleware in a closure, it
uses the error handler signature:
function ($error, ServerRequestInterface $request, ResponseInterface $response, callable $next);
Read the section on piping vs routing for more information.
Registering routing middleware
Routing is accomplished via dedicated a dedicated middleware method,
Application::routeMiddleware()
. It is an instance method, and can be
piped/registered with other middleware platforms if desired.
Internally, the first time route()
is called (including via one of the proxy
methods), or, if never called, when __invoke()
(the exposed application
middleware) is called, the instance will pipe Application::routeMiddleware
to
the middleware pipeline. You can also pipe it manually if desired:
$app->pipeRoutingMiddleware();
Retrieving dependencies
As noted in the intro, the Application
class has several dependencies. Some of
these may allow further configuration, or may be useful on their own, and have
methods for retrieving them. They include:
getContainer()
: returns the composed container-interop instance (used to retrieve routed middleware).getEmitter()
: returns the composed emitter, typically aZend\Expressive\Emitter\EmitterStack
instance.getFinalHandler(ResponseInterface $response = null)
: retrieves the final handler instance. This is middleware with the signaturefunction ($request, $response, $error = null)
, and it is invoked when the middleware pipeline queue is depleted and no response has been returned.
Executing the application: run()
When the application is completely setup, you can execute it with the run()
method. The method may be called with no arguments, but has the following
signature:
public function run(
ServerRequestInterface $request = null,
ResponseInterface $response = null
);