From ac1d6dc38e93e74d770d9a3a1e49fa15a090e83c Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 7 Apr 2023 08:50:40 +0900 Subject: [PATCH 1/7] docs: change note to important --- user_guide_src/source/incoming/controllers.rst | 2 +- user_guide_src/source/incoming/routing.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index 232e7c169a42..a6e9f7b002a3 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/user_guide_src/source/incoming/controllers.rst @@ -274,7 +274,7 @@ 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. diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index fffa5cb1bdb8..4b1d215355f6 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/user_guide_src/source/incoming/routing.rst @@ -681,7 +681,7 @@ The default controller is also used when no matching route has been found, and t 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 +698,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: From 08799135995788ef64186d6b77b6078409746c0f Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 7 Apr 2023 08:52:03 +0900 Subject: [PATCH 2/7] docs: improve description for Default Controller in Auto-Routing Improved --- .../source/incoming/controllers.rst | 20 +++++++++++++------ user_guide_src/source/incoming/routing.rst | 12 ++++++++++- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index a6e9f7b002a3..7a58e0c04c02 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/user_guide_src/source/incoming/controllers.rst @@ -278,12 +278,17 @@ Your method will be passed URI segments 3 and 4 (``'sandals'`` and ``'123'``): 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 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. + 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 ================================================ diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index 4b1d215355f6..cf3d5d994394 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,12 +673,20 @@ 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. From 507b418fa3fd25ab7f37f09ee3ceeb2a6c91a6b8 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 7 Apr 2023 08:57:57 +0900 Subject: [PATCH 3/7] docs: remove / at the end of "app/Controllers/" directory The directory name is "app/Controllers", not "app/Controllers/". --- user_guide_src/source/incoming/controllers.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index 7a58e0c04c02..6885cc27db74 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,7 +218,7 @@ 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. + 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. If you want another naming convention you need to manually define it using the @@ -319,7 +319,7 @@ 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. @@ -333,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. @@ -381,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. @@ -410,7 +411,7 @@ 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. + 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. If you want another naming convention you need to manually define it using the @@ -488,7 +489,7 @@ 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. @@ -502,7 +503,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. From 3da0ef918eb3fbc4c92e5dce114b2b191e29ccf8 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 7 Apr 2023 09:01:53 +0900 Subject: [PATCH 4/7] docs: replace folder with directory For consistency. --- user_guide_src/source/incoming/controllers.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index 6885cc27db74..eb5666f48981 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/user_guide_src/source/incoming/controllers.rst @@ -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 `. @@ -322,10 +322,10 @@ permits you to do this. 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 @@ -411,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 `. @@ -492,10 +492,10 @@ permits you to do this. 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 From ebee1aaee29e56f6106de8696a1853f004814603 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 7 Apr 2023 09:16:41 +0900 Subject: [PATCH 5/7] docs: add (Legacy) in section titles --- user_guide_src/source/incoming/controllers.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index eb5666f48981..e93291c57080 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/user_guide_src/source/incoming/controllers.rst @@ -368,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 @@ -420,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 @@ -442,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. @@ -482,8 +482,8 @@ see the "Hello World" message. For more information, please refer to the :ref:`routes-configuration-options` section of the :doc:`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 From 4ebf0e7b9aad8e6fde24461f78dac9a4faa09613 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 7 Apr 2023 09:17:22 +0900 Subject: [PATCH 6/7] docs: improve description for Default Controller in Auto-Routing Legacy --- user_guide_src/source/incoming/controllers.rst | 17 +++++++++++------ user_guide_src/source/incoming/routing.rst | 8 ++++++++ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index e93291c57080..04ae8a4b5957 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/user_guide_src/source/incoming/controllers.rst @@ -456,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) +=========================== -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. +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. + +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: @@ -480,7 +485,7 @@ 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 (Legacy) ========================================================= diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index cf3d5d994394..18699f6393fd 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/user_guide_src/source/incoming/routing.rst @@ -757,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) ============================== @@ -765,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. From 095d063786c112ddedca0421d606773d7af401a2 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 10 Apr 2023 09:34:34 +0900 Subject: [PATCH 7/7] docs: fix typo Co-authored-by: Michal Sniatala --- user_guide_src/source/incoming/controllers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/incoming/controllers.rst b/user_guide_src/source/incoming/controllers.rst index 04ae8a4b5957..03e962bd4f12 100644 --- a/user_guide_src/source/incoming/controllers.rst +++ b/user_guide_src/source/incoming/controllers.rst @@ -281,7 +281,7 @@ Your method will be passed URI segments 3 and 4 (``'sandals'`` and ``'123'``): Default Controller ================== -The Default Controller is a special controller that is used when a URI end with +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.