[ci skip] Add a upgrade notes about default_controller, 404_override

1 files changed, 50 insertions, 13 deletions

diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst
index 8983f3d18..73ed0f4c3 100644
--- a/user_guide_src/source/installation/upgrade_300.rst
+++ b/user_guide_src/source/installation/upgrade_300.rst
@@ -212,26 +212,63 @@ is suitable for the command line. This of course requires another level of separ
 It is safe to move your old templates from _application/errors* to _application/views/errors/html*,
 but you'll have to copy the new _application/views/errors/cli* directory from the CodeIgniter archive.
 
-*******************************************************
-Step 9: Update your config/routes.php containing (:any)
-*******************************************************
+******************************************
+Step 9: Update your config/routes.php file
+******************************************
 
-Historically, CodeIgniter has always provided the **:any** wildcard in routing,
-with the intention of providing a way to match any character **within** an URI segment.
+Routes containing :any
+======================
+
+Historically, CodeIgniter has always provided the **:any** wildcard in
+routing, with the intention of providing a way to match any character
+**within** an URI segment.
+
+However, the **:any** wildcard is actually just an alias for a regular
+expression and used to be executed in that manner as **.+**. This is
+considered a bug, as it also matches the / (forward slash) character, which
+is the URI segment delimiter and that was never the intention.
 
-However, the **:any** wildcard is actually just an alias for a regular expression
-and used to be executed in that manner as **.+**. This is considered a bug, as it
-also matches the / (forward slash) character, which is the URI segment delimiter
-and that was never the intention. In CodeIgniter 3, the **:any** wildcard will now
-represent **[^/]+**, so that it will not match a forward slash.
+In CodeIgniter 3, the **:any** wildcard will now represent **[^/]+**, so
+that it will not match a forward slash.
 
-There are certainly many developers that have utilized this bug as an actual feature.
-If you're one of them and want to match a forward slash, please use the **.+**
-regular expression::
+There are certainly many developers that have utilized this bug as an actual
+feature. If you're one of them and want to match a forward slash, please use
+the **.+** regular expression::
 
 	(.+)	// matches ANYTHING
 	(:any)	// matches any character, except for '/'
 
+Directories and 'default_controller', '404_override'
+====================================================
+
+As you should know, the ``$route['default_controller']`` and
+``$route['404_override']`` settings accept not only a controller name, but
+also *controller/method* pairs. However, a bug in the routing logic has
+made it possible for some users to use that as *directory/controller*
+instead.
+
+As already said, this behavior was incidental and was never intended, nor
+documented. If you've relied on it, your application will break with
+CodeIgniter 3.0.
+
+Another notable change in version 3 is that 'default_controller' and
+'404_override' are now applied *per directory*. To explain what this means,
+let's take the following example::
+
+	$route['default_controller'] = 'main';
+
+Now, assuming that your website is located at *example.com*, you already
+know that if a user visits ``http://example.com/``, the above setting will
+cause your 'Main' controller to be loaded.
+
+However, what happens if you have an *application/controllers/admin/*
+directory and the user visits ``http://example.com/admin/``?
+In CodeIgniter 3, the router will look for a 'Main' controller under the
+admin/ directory as well. If not found, it will fallback to the parent
+(*application/controllers/*) directory, like in version 2.x.
+
+The same rule applies to the '404_override' setting.
+
 *************************************************************************
 Step 10: Many functions now return NULL instead of FALSE on missing items
 *************************************************************************