forked from fuel/docs
-
Notifications
You must be signed in to change notification settings - Fork 118
/
Copy pathrouting.html
233 lines (177 loc) · 9.1 KB
/
routing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="./../assets/css/combined.css">
<link rel="shortcut icon" href="./../favicon.ico" />
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
<script type="text/javascript">
var path = './../';
</script>
<script src="./../assets/js/combined.js"></script>
<title>Routing - General - FuelPHP Documentation</title>
</head>
<body>
<div id="container">
<header id="header">
<div class="table">
<h1>
<a href="http://fuelphp.com"><img height="37px" width="147px" src="./../assets/img/fuel.png" /></a>
<strong>Documentation</strong>
</h1>
<form id="google_search">
<p>
<span id="search_clear"> </span>
<input type="submit" name="search_submit" id="search_submit" value="search" />
<input type="text" value="" id="search_input" name="search_input" />
</p>
</form>
</div>
<nav>
<div class="clear"></div>
</nav>
<a href="#" id="toc_handle">table of contents</a>
<div class="clear"></div>
</header>
<div id="cse">
<div id="cse_point"></div>
<div id="cse_content"></div>
</div>
<div id="main">
<h2>Routing</h2>
<p>Fuel's routing can range from simple static routes to advanced routes using HTTP verb based routing.</p>
<p>Routes are set in <kbd>fuel/app/config/routes.php</kbd>.</p>
<h3 id="reserved">Reserved Routes</h3>
<p>In Fuel there are 4 reserved routes. They are <kbd>_root_</kbd>, <kbd>_403_</kbd>, <kbd>_404_</kbd> and <kbd>_500_</kbd>.</p>
<ul>
<li><kbd>_root_</kbd> - The default route when no URI is specified.</li>
<li><kbd>_403_</kbd> - The route used when the application throws an HttpNoAccessException that isn't caught.</li>
<li><kbd>_404_</kbd> - The route used when the application throws an HttpNotFoundException that isn't caught.</li>
<li><kbd>_500_</kbd> - The route used when the application throws an HttpServerErrorException that isn't caught.</li>
</ul>
<p class="note">
The request class throws an HttpNotFoundException when you request a URI (a route) that your application
can't resolve.
</p>
<p class="note">
If no <kbd>_404_</kbd> route is defined, the framework uses it's own error handler to display
a "page not found" message. If no <kbd>_403_</kbd> or <kbd>_500_</kbd> route is defined, these
exceptions remain uncaught, and are handled like any other exception your application might throw.
</p>
<pre class="php"><code>return array(
'_root_' => 'welcome/index',
'_404_' => 'welcome/404',
);</code></pre>
<h3 id="basics">Basic Routing</h3>
<p>The route on the left is compared to the request URI. If a match is found, the request is routed to the URI on the right.</p>
<p>This allows you to do things like the following:</p>
<pre class="php"><code>return array(
'about' => 'site/about',
'contact' => 'contact/form',
'admin' => 'admin/login',
);</code></pre>
<h3 id="slightly_advanced">Slightly Advanced Routing</h3>
<p>You can include any regex into your routes. The left side is matched against the
requests URI, and the right side is the replacement for the left, so you can use
backreferences in the right side from the regex on the left. There are also a few
special statements that allow you match anything or just a segment:</p>
<ul>
<li><kbd>:any</kbd> - This matches anything from that point on in the URI, does not match "nothing"</li>
<li><kbd>:everything</kbd> - Like <kbd>:any</kbd>, but also matches "nothing"</li>
<li><kbd>:segment</kbd> - This matches only 1 segment in the URI, but that segment can be anything</li>
<li><kbd>:num</kbd> - This matches any numbers</li>
<li><kbd>:alpha</kbd> - This matches any alpha characters, including UTF-8</li>
<li><kbd>:alnum</kbd> - This matches any alphanumeric characters, including UTF-8</li>
</ul>
<p>Here are some examples. Notice the subtle differences between <kbd>:any</kbd> and <kbd>:everything</kbd>:</p>
<pre class="php"><code>return array(
'blog/(:any)' => 'blog/entry/$1', // Routes /blog/entry_name to /blog/entry/entry_name
// matches /blog/, does not match /blogging and /blog
'blog(:any)' => 'blog/entry$1', // Routes /blog/entry_name to /blog/entry/entry_name
// matches /blog/ and /blogging, does not match /blog
'blog(:everything)' => 'blog/entry$1', // Routes /blog/entry_name to /blog/entry/entry_name
// matches /blog/, /blogging and /blog
'(:segment)/about' => 'site/about/$1', // Routes /en/about to /site/about/en
'(\d{2})/about' => 'site/about/$1', // Routes /12/about to /site/about/12
);</code></pre>
<h3 id="advanced">Advanced Routing</h3>
<p>You can also have named parameters in your routes. This allows you to give your URI segments
names which can then be accessed from within your actions.</p>
<p>Example:</p>
<pre class="php"><code>return array(
'blog/:year/:month/:id' => 'blog/entry', // Routes /blog/2010/11/entry_name to /blog/entry
);</code></pre>
<p>In the above example it would catch the following <kbd>/blog/2010/11/entry_name</kbd>. It would then
route that request to your 'entry' action in your 'blog' controller. There, the named params
will be available like this:</p>
<pre class="php"><code>$this->param('year');
$this->param('month');
$this->param('id');</code></pre>
<p class="note">
Note that as a named parameter is a regex, every named parameter counts as a backreference.
So in a route like ':name/(\d{2})', the backreference for your two-digit segment is $2, not $1!</p>
<h3 id="http_verb">HTTP verb based routing</h3>
<p>You can route your URLs to controllers and actions based on the HTTP verb used to call them.
This makes it quick and easy to make RESTful controllers.</p>
<p>Example:</p>
<pre class="php"><code>return array(
// Routes GET /blog to /blog/all and POST /blog to /blog/create
'blog' => array(array('GET', new Route('blog/all')), array('POST', new Route('blog/create'))),
);</code></pre>
<p>You can use named parameters and regexes within your URL just like normal:</p>
<pre class="php"><code>return array(
'blog/(:any)' => array(array('GET', new Route('blog/show/$1'))),
);</code></pre>
<p>You can also specify if this route is supported for only http, or only https, by passing <kbd>false</kbd> or <kbd>true</kbd> as third parameter:</p>
<pre class="php"><code>// route only valid if this is an https request
return array(
'blog/(:any)' => array(array('GET', new Route('blog/show/$1'), true)),
);</code></pre>
<h3 id="named_routes">Named routes and reverse routing</h3>
<p>The idea of reversed routing is like this: say you got an admin area and you have a route setup for it.
In your views, you would like to that admin area using an HTML anchor that links to for example 'admin/start/overview'.
Now you decide to move stuff around and end up moving that specific page to 'admin/overview'.
As a result of this now you need to update the links in all your views...</p>
<p>When using reverse routing with these name routes you can link an anchor to a named route, so that when the route changes,
the links in your views will automatically follow the change</p>
<p>Example route:</p>
<pre class="php"><code>return array(
'admin/start/overview' => array('admin/overview', 'name' => 'admin_overview'), // add a named route for the admin/overview page
);</code></pre>
<p>Example anchor:</p>
<pre class="php"><code>// produces <a href="http://your_base_url/admin/start/overview">Overview</a>
echo Html::anchor(Router::get('admin_overview'), 'Overview');</code></pre>
<p class="note">
Note that this currently only works for routes that are defined in <kbd>app/config/routes.php</kbd>, not for module routes.
</p>
<h3 id="inline_routes">Inline routes</h3>
<p>
A route does not have to resolve to a controller method. FuelPHP also supports inline routes, which are defined as a Closure
that replaces the controller method. Like controller methods, inline routes MUST return a Response object, either by forging
one manually, or as the result of executing a forged Request.
</p>
<p>Example route:</p>
<pre class="php"><code>return array(
'secret/mystuff' => function () {
// this route only works in development
if (\Fuel::$env == \Fuel::DEVELOPMENT)
{
return \Request::forge('secret/mystuff/keepout', false)->execute();
}
else
{
throw new HttpNotFoundException('This page is only accessable in development.');
}
};</code></pre>
<h3 id="module_routing">Modules & Routing</h3>
<p><a href="modules.html#module_routing">Read about how modules handle routing</a>.</p>
</div>
<footer>
<p>
© FuelPHP Development Team 2010-2016 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
</p>
</footer>
</div>
</body>
</html>