Skip to content
This repository was archived by the owner on Jan 29, 2020. It is now read-only.

Commit a79eccf

Browse files
committed
Updated features flow diagram and narrative.
Removes the `pre_routing` and `post_routing` verbiage.
1 parent 178dd19 commit a79eccf

File tree

5 files changed

+42
-15
lines changed

5 files changed

+42
-15
lines changed

doc/book/features.md

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -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

104116
Routing within Expressive consists of decomposing the request to match it to
105117
middleware 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+
112129
The majority of your application will consist of routing rules that map to
113130
routed 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

123142
Such middleware may decide that a request is invalid, and return a response;
124143
doing so means no further middleware will be executed! This is an important
125144
feature of middleware architectures, as it allows you to define
126145
application-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.
134154
One possibility is for [providing custom 404 handling](cookbook/custom-404-page-handling.md),
135155
or handling application-specific error conditions (such as authentication or
136156
authorization failures).
137157

138158
Another 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
143163
function ($request, $response, $next)

doc/book/images/architecture.dia

126 Bytes
Binary file not shown.

doc/book/images/architecture.png

6.23 KB
Loading

doc/book/images/architecture.svg

Lines changed: 13 additions & 6 deletions
Loading

doc/book/images/architecture.xcf

12.6 KB
Binary file not shown.

0 commit comments

Comments
 (0)