208 lines
6.8 KiB
ReStructuredText
208 lines
6.8 KiB
ReStructuredText
###########
|
|
URI Routing
|
|
###########
|
|
|
|
Typically there is a one-to-one relationship between a URL string and
|
|
its corresponding controller class/method. The segments in a URI
|
|
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/method can be called instead of the one
|
|
corresponding to the URL.
|
|
|
|
For example, let's 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/
|
|
|
|
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.
|
|
|
|
Wildcards
|
|
=========
|
|
|
|
A typical wildcard route might look something like this::
|
|
|
|
$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
|
|
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, the
|
|
"catalog" class and the "product_lookup" method are instead used.
|
|
|
|
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 (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';
|
|
|
|
A URL containing the word "journals" in the first segment will be
|
|
remapped to the "blogs" class.
|
|
|
|
::
|
|
|
|
$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';
|
|
|
|
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.
|
|
|
|
::
|
|
|
|
$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 method.
|
|
|
|
.. important:: Do not use leading/trailing slashes.
|
|
|
|
Regular Expressions
|
|
===================
|
|
|
|
If you prefer you can use regular expressions to define your routing
|
|
rules. Any valid regular expression is allowed, as are back-references.
|
|
|
|
.. note:: If you use back-references you must use the dollar syntax
|
|
rather than the double backslash syntax.
|
|
|
|
A typical RegEx route might look something like this::
|
|
|
|
$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" method.
|
|
|
|
With regular expressions, you can also catch multiple segments at once.
|
|
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';
|
|
|
|
.. note:: In the above example, if the ``$1`` placeholder contains a
|
|
slash, it will still be split into multiple parameters when
|
|
passed to ``Auth::login()``.
|
|
|
|
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
|
|
=========
|
|
|
|
You can also use callbacks in place of the normal routing rules to process
|
|
the back-references. Example::
|
|
|
|
$route['products/([a-zA-Z]+)/edit/(\d+)'] = function ($product_type, $id)
|
|
{
|
|
return 'catalog/product_edit/' . strtolower($product_type) . '/' . $id;
|
|
};
|
|
|
|
Using HTTP verbs in routes
|
|
==========================
|
|
|
|
It is possible to use HTTP verbs (request method) to define your routing rules.
|
|
This is particularly useful when building RESTful applications. You can use standard HTTP
|
|
verbs (GET, PUT, POST, DELETE, PATCH) or a custom one such (e.g. PURGE). HTTP verb rules
|
|
are case-insensitive. All you need to do is to add the verb as an array key to your route.
|
|
Example::
|
|
|
|
$route['products']['put'] = 'product/insert';
|
|
|
|
In the above example, a PUT request to URI "products" would call the ``Product::insert()``
|
|
controller method.
|
|
|
|
::
|
|
|
|
$route['products/(:num)']['DELETE'] = 'product/delete/$1';
|
|
|
|
A DELETE request to URL with "products" as first the segment and a number in the second will be
|
|
mapped to the ``Product::delete()`` method, passing the numeric value as the first parameter.
|
|
|
|
Using HTTP verbs is of course, optional.
|
|
|
|
Reserved Routes
|
|
===============
|
|
|
|
There are three reserved routes::
|
|
|
|
$route['default_controller'] = 'welcome';
|
|
|
|
This route points to the action that should be executed if the URI contains
|
|
no data, which will be the case when people load your root URL.
|
|
The setting accepts a **controller/method** value and ``index()`` would be
|
|
the default method if you don't specify one. In the above example, it is
|
|
``Welcome::index()`` that would be called.
|
|
|
|
.. note:: You can NOT use a directory as a part of this setting!
|
|
|
|
You are encouraged to always have a default route as otherwise a 404 page
|
|
will appear by default.
|
|
|
|
::
|
|
|
|
$route['404_override'] = '';
|
|
|
|
This route indicates which controller class should be loaded if the
|
|
requested controller is not found. It will override the default 404
|
|
error page. Same per-directory rules as with 'default_controller'
|
|
apply here as well.
|
|
|
|
It won't affect to the ``show_404()`` function, which will
|
|
continue loading the default *error_404.php* file at
|
|
*application/views/errors/error_404.php*.
|
|
|
|
::
|
|
|
|
$route['translate_uri_dashes'] = FALSE;
|
|
|
|
As evident by the boolean value, this is not exactly a route. This
|
|
option enables you to automatically replace dashes ('-') with
|
|
underscores in the controller and method URI segments, thus saving you
|
|
additional route entries if you need to do that.
|
|
This is required, because the dash isn't a valid class or method name
|
|
character and would cause a fatal error if you try to use it.
|