summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/general/routing.rst
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2018-01-13 12:57:11 +0100
committerAndrey Andreev <narf@devilix.net>2018-01-13 12:57:11 +0100
commit02a0518e1c56ba3506f370362ac5ebdb8a138312 (patch)
tree8b4684192b403dcae17d298eb4fc9e7ab001acad /user_guide_src/source/general/routing.rst
parentf0b9735d5857e6c07c8f5824b13cff4828db3cfe (diff)
[ci skip] 3.1.7 release
Diffstat (limited to 'user_guide_src/source/general/routing.rst')
-rw-r--r--user_guide_src/source/general/routing.rst207
1 files changed, 0 insertions, 207 deletions
diff --git a/user_guide_src/source/general/routing.rst b/user_guide_src/source/general/routing.rst
deleted file mode 100644
index 909289d8d..000000000
--- a/user_guide_src/source/general/routing.rst
+++ /dev/null
@@ -1,207 +0,0 @@
-###########
-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.