Merge pull request #7414 from kenjis/docs-auto-routing

docs: improve auto routing

Author: kenjis

user_guide_src/source/incoming/controllers.rst

@@ -187,7 +187,7 @@ controllers. You can extend this class in any new controller.
 
 .. literalinclude:: controllers/020.php
 
-Then save the file to your **app/Controllers/** directory.
+Then save the file to your **app/Controllers** directory.
 
 .. important:: The file must be called **Helloworld.php**, with a capital ``H``. When you use Auto Routing, Controller class names MUST start with an uppercase letter and ONLY the first character can be uppercase.
 
@@ -218,8 +218,8 @@ class so that it can inherit all its methods.
 
 .. note::
     The system will attempt to match the URI against Controllers by matching each segment against
-    folders/files in **app/Controllers/**, when a match wasn't found against defined routes.
-    That's why your folders/files MUST start with a capital letter and the rest MUST be lowercase.
+    directories/files in **app/Controllers**, when a match wasn't found against defined routes.
+    That's why your directories/files MUST start with a capital letter and the rest MUST be lowercase.
 
     If you want another naming convention you need to manually define it using the
     :ref:`Defined Route Routing <defined-route-routing>`.
@@ -274,16 +274,21 @@ Your method will be passed URI segments 3 and 4 (``'sandals'`` and ``'123'``):
 
 .. literalinclude:: controllers/022.php
 
-.. note:: If there are more parameters in the URI than the method parameters,
+.. important:: If there are more parameters in the URI than the method parameters,
     Auto Routing (Improved) does not execute the method, and it results in 404
     Not Found.
 
+Default Controller
+==================
+
+The Default Controller is a special controller that is used when a URI ends with
+a directory name or when a URI is not present, as will be the case when only your
+site root URL is requested.
+
 Defining a Default Controller
-=============================
+-----------------------------
 
-CodeIgniter can be told to load a default controller when a URI is not
-present, as will be the case when only your site root URL is requested. Let's try it
-with the ``Helloworld`` controller.
+Let's try it with the ``Helloworld`` controller.
 
 To specify a default controller open your **app/Config/Routes.php**
 file and set this variable:
@@ -299,10 +304,13 @@ A few lines further down **Routes.php** in the "Route Definitions" section, comm
 If you now browse to your site without specifying any URI segments you'll
 see the "Hello World" message.
 
-.. note:: The line ``$routes->get('/', 'Home::index');`` is an optimization that you will want to use in a "real-world" app. But for demonstration purposes we don't want to use that feature. ``$routes->get()`` is explained in :doc:`URI Routing <routing>`
+.. important:: When you use Auto Routing (Improved), you must remove the line
+    ``$routes->get('/', 'Home::index');``. Because defined routes take
+    precedence over Auto Routing, and controllers defined in the defined routes
+    are denied access by Auto Routing (Improved) for security reasons.
 
 For more information, please refer to the :ref:`routes-configuration-options` section of the
-:doc:`URI Routing <routing>` documentation.
+:ref:`URI Routing <routing-auto-routing-improved-configuration-options>` documentation.
 
 Organizing Your Controllers into Sub-directories
 ================================================
@@ -311,21 +319,22 @@ If you are building a large application you might want to hierarchically
 organize or structure your controllers into sub-directories. CodeIgniter
 permits you to do this.
 
-Simply create sub-directories under the main **app/Controllers/**,
+Simply create sub-directories under the main **app/Controllers**,
 and place your controller classes within them.
 
-.. important:: Folder names MUST start with an uppercase letter and ONLY the first character can be uppercase.
+.. important:: Directory names MUST start with an uppercase letter and ONLY the first character can be uppercase.
 
 When using this feature the first segment of your URI must
-specify the folder. For example, let's say you have a controller located here::
+specify the directory. For example, let's say you have a controller located here::
 
     app/Controllers/Products/Shoes.php
 
 To call the above controller your URI will look something like this::
 
     example.com/index.php/products/shoes/show/123
 
-.. note:: You cannot have directories with the same name in **app/Controllers/** and **public/**.
+.. note:: You cannot have directories with the same name in **app/Controllers**
+    and **public**.
     This is because if there is a directory, the web server will search for it and
     it will not be routed to CodeIgniter.
 
@@ -359,8 +368,8 @@ In the above example, CodeIgniter would attempt to find a controller named **Hel
 
 .. note:: When a controller's short name matches the first segment of a URI, it will be loaded.
 
-Let's try it: Hello World!
-==========================
+Let's try it: Hello World! (Legacy)
+===================================
 
 Let's create a simple controller so you can see it in action. Using your text editor, create a file called **Helloworld.php**,
 and put the following code in it. You will notice that the ``Helloworld`` Controller is extending the ``BaseController``. you can
@@ -373,7 +382,7 @@ For security reasons be sure to declare any new utility methods as ``protected``
 
 .. literalinclude:: controllers/008.php
 
-Then save the file to your **app/Controllers/** directory.
+Then save the file to your **app/Controllers** directory.
 
 .. important:: The file must be called **Helloworld.php**, with a capital ``H``. When you use Auto Routing, Controller class names MUST start with an uppercase letter and ONLY the first character can be uppercase.
 
@@ -402,17 +411,17 @@ class so that it can inherit all its methods.
 
 .. note::
     The system will attempt to match the URI against Controllers by matching each segment against
-    folders/files in **app/Controllers/**, when a match wasn't found against defined routes.
-    That's why your folders/files MUST start with a capital letter and the rest MUST be lowercase.
+    directories/files in **app/Controllers**, when a match wasn't found against defined routes.
+    That's why your directories/files MUST start with a capital letter and the rest MUST be lowercase.
 
     If you want another naming convention you need to manually define it using the
     :ref:`Defined Route Routing <defined-route-routing>`.
     Here is an example based on PSR-4 Autoloader:
 
     .. literalinclude:: controllers/012.php
 
-Methods
-=======
+Methods (Legacy)
+================
 
 In the above example, the method name is ``index()``. The ``index()`` method
 is always loaded by default if the **second segment** of the URI is
@@ -433,8 +442,8 @@ Now load the following URL to see the comment method::
 
 You should see your new message.
 
-Passing URI Segments to Your Methods
-====================================
+Passing URI Segments to Your Methods (Legacy)
+=============================================
 
 If your URI contains more than two segments they will be passed to your
 method as parameters.
@@ -447,12 +456,17 @@ Your method will be passed URI segments 3 and 4 (``'sandals'`` and ``'123'``):
 
 .. literalinclude:: controllers/014.php
 
-Defining a Default Controller
-=============================
+Default Controller (Legacy)
+===========================
+
+The Default Controller is a special controller that is used when a URI end with
+a directory name or when a URI is not present, as will be the case when only your
+site root URL is requested.
 
-CodeIgniter can be told to load a default controller when a URI is not
-present, as will be the case when only your site root URL is requested. Let's try it
-with the ``Helloworld`` controller.
+Defining a Default Controller (Legacy)
+--------------------------------------
+
+Let's try it with the ``Helloworld`` controller.
 
 To specify a default controller open your **app/Config/Routes.php**
 file and set this variable:
@@ -471,30 +485,30 @@ see the "Hello World" message.
 .. note:: The line ``$routes->get('/', 'Home::index');`` is an optimization that you will want to use in a "real-world" app. But for demonstration purposes we don't want to use that feature. ``$routes->get()`` is explained in :doc:`URI Routing <routing>`
 
 For more information, please refer to the :ref:`routes-configuration-options` section of the
-:doc:`URI Routing <routing>` documentation.
+:ref:`URI Routing <routing-auto-routing-legacy-configuration-options>` documentation.
 
-Organizing Your Controllers into Sub-directories
-================================================
+Organizing Your Controllers into Sub-directories (Legacy)
+=========================================================
 
 If you are building a large application you might want to hierarchically
 organize or structure your controllers into sub-directories. CodeIgniter
 permits you to do this.
 
-Simply create sub-directories under the main **app/Controllers/**,
+Simply create sub-directories under the main **app/Controllers**,
 and place your controller classes within them.
 
-.. important:: Folder names MUST start with an uppercase letter and ONLY the first character can be uppercase.
+.. important:: Directory names MUST start with an uppercase letter and ONLY the first character can be uppercase.
 
 When using this feature the first segment of your URI must
-specify the folder. For example, let's say you have a controller located here::
+specify the directory. For example, let's say you have a controller located here::
 
     app/Controllers/Products/Shoes.php
 
 To call the above controller your URI will look something like this::
 
     example.com/index.php/products/shoes/show/123
 
-.. note:: You cannot have directories with the same name in **app/Controllers/** and **public/**.
+.. note:: You cannot have directories with the same name in **app/Controllers** and **public/**.
     This is because if there is a directory, the web server will search for it and
     it will not be routed to CodeIgniter.
 

user_guide_src/source/incoming/routing.rst

@@ -663,6 +663,8 @@ and executes ``getHello()`` method with passing ``'1'`` as the first argument.
 
 See :ref:`Auto Routing in Controllers <controller-auto-routing-improved>` for more info.
 
+.. _routing-auto-routing-improved-configuration-options:
+
 Configuration Options
 =====================
 
@@ -671,17 +673,25 @@ These options are available at the top of **app/Config/Routes.php**.
 Default Controller
 ------------------
 
+For Site Root URI
+^^^^^^^^^^^^^^^^^
+
 When a user visits the root of your site (i.e., **example.com**) the controller to use is determined by the value set by
-the ``setDefaultController()`` method, unless a route exists for it explicitly. The default value for this is ``Home``
+the ``setDefaultController()`` method, unless a route exists for it explicitly.
+
+The default value for this is ``Home``
 which matches the controller at **app/Controllers/Home.php**:
 
 .. literalinclude:: routing/047.php
 
+For Directory URI
+^^^^^^^^^^^^^^^^^
+
 The default controller is also used when no matching route has been found, and the URI would point to a directory
 in the controllers directory. For example, if the user visits **example.com/admin**, if a controller was found at
 **app/Controllers/Admin/Home.php**, it would be used.
 
-.. note:: You cannot access the default controller with the URI of the controller name.
+.. important:: You cannot access the default controller with the URI of the controller name.
     When the default controller is ``Home``, you can access **example.com/**, but if you access **example.com/home**, it will be not found.
 
 See :ref:`Auto Routing in Controllers <controller-auto-routing-improved>` for more info.
@@ -698,7 +708,7 @@ In this example, if the user were to visit **example.com/products**, and a ``Pro
 
 .. literalinclude:: routing/048.php
 
-.. note:: You cannot access the controller with the URI of the default method name.
+.. important:: You cannot access the controller with the URI of the default method name.
     In the example above, you can access **example.com/products**, but if you access **example.com/products/listall**, it will be not found.
 
 .. _auto-routing-legacy:
@@ -747,6 +757,8 @@ and executes ``index()`` method with passing ``'1'`` as the first argument.
 
 See :ref:`Auto Routing (Legacy) in Controllers <controller-auto-routing-legacy>` for more info.
 
+.. _routing-auto-routing-legacy-configuration-options:
+
 Configuration Options (Legacy)
 ==============================
 
@@ -755,12 +767,18 @@ These options are available at the top of **app/Config/Routes.php**.
 Default Controller (Legacy)
 ---------------------------
 
+For Site Root URI (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 When a user visits the root of your site (i.e., example.com) the controller to use is determined by the value set by
 the ``setDefaultController()`` method, unless a route exists for it explicitly. The default value for this is ``Home``
 which matches the controller at **app/Controllers/Home.php**:
 
 .. literalinclude:: routing/047.php
 
+For Directory URI (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The default controller is also used when no matching route has been found, and the URI would point to a directory
 in the controllers directory. For example, if the user visits **example.com/admin**, if a controller was found at
 **app/Controllers/Admin/Home.php**, it would be used.