diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index 232e7c169a42..03e962bd4f12 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/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 `. @@ -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 ` +.. 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 ` documentation. +:ref:`URI Routing ` documentation. Organizing Your Controllers into Sub-directories ================================================ @@ -311,13 +319,13 @@ 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 @@ -325,7 +333,8 @@ 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,8 +411,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 `. @@ -411,8 +420,8 @@ class so that it can inherit all its methods. .. 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,22 +485,22 @@ 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 ` For more information, please refer to the :ref:`routes-configuration-options` section of the -:doc:`URI Routing ` documentation. +:ref:`URI Routing ` 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 @@ -494,7 +508,7 @@ 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. diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index fffa5cb1bdb8..18699f6393fd 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/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 ` 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 ` 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 ` 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.