diff options
Diffstat (limited to 'user_guide_src/source/general/routing.rst')
| -rw-r--r-- | user_guide_src/source/general/routing.rst | 90 |
1 files changed, 63 insertions, 27 deletions
diff --git a/user_guide_src/source/general/routing.rst b/user_guide_src/source/general/routing.rst index 45950fc11..2a0332088 100644 --- a/user_guide_src/source/general/routing.rst +++ b/user_guide_src/source/general/routing.rst @@ -9,34 +9,34 @@ normally follow this pattern:: example.com/class/function/id/ In some instances, however, you may want to remap this relationship so -that a different class/function can be called instead of the one +that a different class/method can be called instead of the one corresponding to the URL. -For example, lets say you want your URLs to have this prototype: +For example, lets say you want your URLs to have this prototype:: -example.com/product/1/ -example.com/product/2/ -example.com/product/3/ -example.com/product/4/ + example.com/product/1/ + example.com/product/2/ + example.com/product/3/ + example.com/product/4/ -Normally the second segment of the URL is reserved for the function -name, but in the example above it instead has a product ID. To overcome -this, CodeIgniter allows you to remap the URI handler. +Normally the second segment of the URL is reserved for the method +name, but in the example above it instead has a product ID. To +overcome this, CodeIgniter allows you to remap the URI handler. Setting your own routing rules ============================== -Routing rules are defined in your application/config/routes.php file. In -it you'll see an array called $route that permits you to specify your -own routing criteria. Routes can either be specified using wildcards or -Regular Expressions +Routing rules are defined in your *application/config/routes.php* file. +In it you'll see an array called ``$route`` that permits you to specify +your own routing criteria. Routes can either be specified using wildcards +or Regular Expressions. Wildcards ========= A typical wildcard route might look something like this:: - $route['product/:num'] = "catalog/product_lookup"; + $route['product/:num'] = 'catalog/product_lookup'; 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. In the @@ -47,31 +47,40 @@ segment of the URL, and a number is found in the second segment, the You can match literal values or you can use two wildcard types: **(:num)** will match a segment containing only numbers. - **(:any)** will match a segment containing any character. +**(:any)** will match a segment containing any character (except for '/', which is the segment delimiter). + +.. note:: Wildcards are actually aliases for regular expressions, with + **:any** being translated to **[^/]+** and **:num** to **[0-9]+**, + respectively. .. note:: Routes will run in the order they are defined. Higher routes will always take precedence over lower ones. +.. note:: Route rules are not filters! Setting a rule of e.g. + 'foo/bar/(:num)' will not prevent controller *Foo* and method + *bar* to be called with a non-numeric value if that is a valid + route. + Examples ======== Here are a few routing examples:: - $route['journals'] = "blogs"; + $route['journals'] = 'blogs'; A URL containing the word "journals" in the first segment will be remapped to the "blogs" class. :: - $route['blog/joe'] = "blogs/users/34"; + $route['blog/joe'] = 'blogs/users/34'; 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". :: - $route['product/(:any)'] = "catalog/product_lookup"; + $route['product/(:any)'] = 'catalog/product_lookup'; A URL with "product" as the first segment, and anything in the second will be remapped to the "catalog" class and the "product_lookup" @@ -79,12 +88,12 @@ method. :: - $route['product/(:num)'] = "catalog/product_lookup_by_id/$1"; + $route['product/(:num)'] = 'catalog/product_lookup_by_id/$1'; A URL with "product" as the first segment, and a number in the second will be remapped to the "catalog" class and the "product_lookup_by_id" method passing in the match as a variable to -the function. +the method. .. important:: Do not use leading/trailing slashes. @@ -99,12 +108,39 @@ rules. Any valid regular expression is allowed, as are back-references. A typical RegEx route might look something like this:: - $route['products/([a-z]+)/(\d+)'] = "$1/id_$2"; + $route['products/([a-z]+)/(\d+)'] = '$1/id_$2'; In the above example, a URI similar to products/shirts/123 would instead -call the shirts controller class and the id_123 function. +call the "shirts" controller class and the "id_123" method. + +With regular expressions, you can also catch a segment containing a +forward slash ('/'), which would usually represent the delimiter between +multiple segments. +For example, if a user accesses a password protected area of your web +application and you wish to be able to redirect them back to the same +page after they log in, you may find this example useful:: + + $route['login/(.+)'] = 'auth/login/$1'; + +That will call the "auth" controller class and its ``login()`` method, +passing everything contained in the URI after *login/* as a parameter. + +For those of you who don't know regular expressions and want to learn +more about them, `regular-expressions.info <http://www.regular-expressions.info/>` +might be a good starting point. + +..note:: You can also mix and match wildcards with regular expressions. + +Callbacks +========= + +If you are using PHP >= 5.3 you can use callbacks in place of the normal +routing rules to process the back-references. Example:: -You can also mix and match wildcards with regular expressions. + $route['products/([a-z]+)/edit/(\d+)'] = function ($product_type, $id) + { + return 'catalog/product_edit/' . strtolower($product_type) . '/' . $id; + }; Reserved Routes =============== @@ -125,9 +161,9 @@ appear by default. This route indicates which controller class should be loaded if the requested controller is not found. It will override the default 404 -error page. It won't affect to the show_404() function, which will -continue loading the default error_404.php file at -application/errors/error_404.php. +error page. It won't affect to the ``show_404()`` function, which will +continue loading the default *error_404.php* file at +*application/errors/error_404.php*. .. important:: The reserved routes must come before any wildcard or - regular expression routes. + regular expression routes.
\ No newline at end of file |