Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 1487f8c96493cac4aa8fb440fb829e20231a6053 / . / user_guide / general / routing.html
blob: d31b0620d52fdb98b6ac0cf5fd691462dcea72f6 [file] [log] [blame]
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Derek Allardafd99ac2008-01-19 19:59:14 +0000[diff] [blame]2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]3<head>
4
Derek Allard404e35d2007-08-07 01:00:45 +0000[diff] [blame]5<title>CodeIgniter User Guide : URI Routing</title>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]6
7<style type='text/css' media='all'>@import url('../userguide.css');</style>
8<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
9
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]10<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]11<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]12<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]13<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]14
15<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +0000[diff] [blame]19<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]20<meta name='description' content='CodeIgniter User Guide' />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.0</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39<!-- START BREADCRUMB -->
40<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
41<tr>
42<td id="breadcrumb">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45URI Routing
46</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]47<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58<h1>URI Routing</h1>
59
admine334c472006-10-21 19:44:22 +0000[diff] [blame]60<p>Typically there is a one-to-one relationship between a URL string and its corresponding controller class/method.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]61The segments in a URI normally follow this pattern:</p>
62
63<code>www.your-site.com/<dfn>class</dfn>/<samp>function</samp>/<var>id</var>/</code>
64
admine334c472006-10-21 19:44:22 +0000[diff] [blame]65<p>In some instances, however, you may want to remap this relationship so that a different class/function can be called
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]66instead of the one corresponding to the URL.</p>
67
68<p>For example, lets say you want your URLs to have this prototype:</p>
69
70<p>
71www.your-site.com/product/1/<br />
72www.your-site.com/product/2/<br />
73www.your-site.com/product/3/<br />
74www.your-site.com/product/4/
75</p>
76
admine334c472006-10-21 19:44:22 +0000[diff] [blame]77<p>Normally the second segment of the URL is reserved for the function name, but in the example above it instead has a product ID.
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]78To overcome this, CodeIgniter allows you to remap the URI handler.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]79
80
81<h2>Setting your own routing rules</h2>
82
admind4e95072006-08-26 01:15:06 +0000[diff] [blame]83<p>Routing rules are defined in your <var>application/config/routes.php</var> file. In it you'll see an array called <dfn>$route</dfn> that
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]84permits you to specify your own routing criteria. Routes can either be specified using <dfn>wildcards</dfn> or <dfn>Regular Expressions</dfn></p>
admind4e95072006-08-26 01:15:06 +0000[diff] [blame]85
86
87<h2>Wildcards</h2>
88
89<p>A typical wildcard route might look something like this:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]90
91<code>$route['product/:num'] = "catalog/product_lookup";</code>
92
admine334c472006-10-21 19:44:22 +0000[diff] [blame]93<p>In a route, the array key contains the URI to be matched, while the array value contains the destination it should be re-routed to.
94In the above example, if the literal word "product" is found in the first segment of the URL, and a number is found in the second segment,
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]95the "catalog" class and the "product_lookup" method are instead used.</p>
96
97<p>You can match literal values or you can use two wildcard types:</p>
98
99<p>
100:num<br />
101:any
102</p>
103
104<p><strong>:num</strong> will match a segment containing only numbers.<br />
105<strong>:any</strong> will match a segment containing any character.
106</p>
107
admine334c472006-10-21 19:44:22 +0000[diff] [blame]108<p class="important"><strong>Note:</strong> Routes will run in the order they are defined.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]109Higher routes will always take precedence over lower ones.</p>
110
111
112<h2>Examples</h2>
113
114<p>Here are a few routing examples:</p>
115
116<code>$route['journals'] = "blogs";</code>
Derek Allard7184f342007-12-26 14:47:10 +0000[diff] [blame]117<p>A URL containing the word "journals" in the first segment will be remapped to the "blogs" class.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]118
119<code>$route['blog/joe'] = "blogs/users/34";</code>
Derek Allard7184f342007-12-26 14:47:10 +0000[diff] [blame]120<p>A URL containing the segments blog/joe will be remapped to the "blogs" class and the "users" method. The ID will be set to "34".</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]121
122
123<code>$route['product/:any'] = "catalog/product_lookup";</code>
Derek Allard7184f342007-12-26 14:47:10 +0000[diff] [blame]124<p>A URL with "product" as the first segment, and anything in the second will be remapped to the "catalog" class and the "product_lookup" method.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]125
126<p class="important"><strong>Important:</strong> Do not use leading/trailing slashes.</p>
127
admind4e95072006-08-26 01:15:06 +0000[diff] [blame]128<h2>Regular Expressions</h2>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]129
admind4e95072006-08-26 01:15:06 +0000[diff] [blame]130<p>If you prefer you can use regular expressions to define your routing rules. Any valid regular expression is allowed, as are back-references.</p>
131
132<p class="important"><strong>Note:</strong>&nbsp; If you use back-references you must use the dollar syntax rather then the double backslash syntax.</p>
133
134<p>A typical RegEx route might look something like this:</p>
135
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]136<code>$route['products/([a-z]+)/(\d+)'] = "$1/id_$2";</code>
admind4e95072006-08-26 01:15:06 +0000[diff] [blame]137
138<p>In the above example, a URI similar to <dfn>products/shirts/123</dfn> would instead call the <dfn>shirts</dfn> controller class and the <dfn>id_123</dfn> function.</p>
139
140<p>You can also mix and match wildcards with regular expressions.</p>
141
142<h2>Reserved Routes</h2>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]143
144<p>There are two reserved routes:</p>
145
146<code>$route['default_controller'] = 'welcome';</code>
147
148<p>This route indicates which controller class should be loaded if the URI contains no data, which will be the case
149when people load your root URL. In the above example, the "welcome" class would be loaded. You
150are encouraged to always have a default route otherwise a 404 page will appear by default.</p>
151
152<code>$route['scaffolding_trigger'] = 'scaffolding';</code>
153
154<p>This route lets you set a secret word, which when present in the URL, triggers the scaffolding feature.
155Please read the <a href="scaffolding.html">Scaffolding</a> page for details.</p>
156
Derek Allard24d95442007-04-30 12:21:37 +0000[diff] [blame]157<p class="important"><strong>Important:</strong>&nbsp; The reserved routes must come before any wildcard or regular expression routes.</p>
admind4e95072006-08-26 01:15:06 +0000[diff] [blame]158
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]159</div>
160<!-- END CONTENT -->
161
162
163<div id="footer">
164<p>
165Previous Topic:&nbsp;&nbsp;<a href="scaffolding.html">Scaffolding</a>
166&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
167<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
168<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
169Next Topic:&nbsp;&nbsp;<a href="errors.html">Error Handling</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]170</p>
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]171<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2007 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]172</div>
173
174</body>
175</html>