@@ -98,8 +98,20 @@ argument to act on.
9898> - Responses are returned back * through* the pipeline, in reverse order of
9999> traversal.
100100
101- The ` Application ` allows for "pre routing" middleware, routing middleware (and
102- the routed middleware it dispatches), and "post routing" middleware.
101+ The ` Application ` allows arbitrary middleware to be injected, with each being
102+ executed in the order in which they are attached; returning a response from
103+ middleware prevents any middleware attached later from executing.
104+
105+ You can attach middleware manually, in which case the pipeline is executed in
106+ the order of attachment, or use configuration. When you use configuration, you
107+ will specify a priority integer to dictate the order in which middleware should
108+ be attached. Middleware specifying high integer prioritiess are attached (and
109+ thus executed) earlier, while those specifying lower and/or negative integers
110+ are attached later. The default priority is 1.
111+
112+ Expressive provides a default implementation of "routing" and "dispatch"
113+ middleware, which you either attach to the middleware pipeline manually, or via
114+ configuration.
103115
104116Routing within Expressive consists of decomposing the request to match it to
105117middleware that can handle that given request. This typically consists of a
@@ -109,35 +121,43 @@ combination of matching the requested URI path along with allowed HTTP methods:
109121- map a POST request to the path ` /contact/process ` to the ` HandleContactMiddleware `
110122- etc.
111123
124+ Dispatching is simply the act of calling the middleware mapped by routing. The
125+ two events are modeled as separate middleware to allow you to act on the results
126+ of routing before attempting to dispatch the mapped middleware; this can be
127+ useful for implementing route-based authentication or validation.
128+
112129The majority of your application will consist of routing rules that map to
113130routed middleware.
114131
115- "Pre routing" middleware is middleware that you wish to execute for every
116- request. These might include:
132+ Middleware piped to the application earlier than routing should be middleware
133+ that you wish to execute for every request. These might include:
117134
118- - authentication
135+ - bootstrapping
119136- parsing of request body parameters
120137- addition of debugging tools
138+ - embedded Expressive applications that you want to match at a given literal
139+ path
121140- etc.
122141
123142Such middleware may decide that a request is invalid, and return a response;
124143doing so means no further middleware will be executed! This is an important
125144feature of middleware architectures, as it allows you to define
126145application-specific workflows optimized for performance, security, etc.
127146
128- "Post routing" middleware will execute in one of two conditions:
147+ Middleware piped to the application after the routing and dispatch middleware
148+ will execute in one of two conditions:
129149
130150- routing failed
131151- routed middleware called on the next middleware instead of returning a response.
132152
133- As such, the largest use case for post routing middleware is for error handling.
153+ As such, the largest use case for such middleware is for error handling.
134154One possibility is for [ providing custom 404 handling] ( cookbook/custom-404-page-handling.md ) ,
135155or handling application-specific error conditions (such as authentication or
136156authorization failures).
137157
138158Another possibility is to provide post-processing on the response before
139- returning it. However, this is typically better handled via pre-routing
140- middleware , by capturing the response before returning it:
159+ returning it. However, this is typically better handled via middleware piped
160+ early , by capturing the response before returning it:
141161
142162``` php
143163function ($request, $response, $next)
0 commit comments