Skip to content

docs: improve auto routing #7414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kenjis merged 7 commits into from
Apr 12, 2023
Merged

docs: improve auto routing #7414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ac1d6dc
docs: change note to important
kenjis Apr 6, 2023
0879913
docs: improve description for Default Controller in Auto-Routing Impr…
kenjis Apr 6, 2023
507b418
docs: remove / at the end of "app/Controllers/" directory
kenjis Apr 6, 2023
3da0ef9
docs: replace folder with directory
kenjis Apr 7, 2023
ebee1aa
docs: add (Legacy) in section titles
kenjis Apr 7, 2023
4ebf0e7
docs: improve description for Default Controller in Auto-Routing Legacy
kenjis Apr 7, 2023
095d063
docs: fix typo
kenjis Apr 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 49 additions & 35 deletions user_guide_src/source/incoming/controllers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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>`.
Expand Down Expand Up @@ -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:
Expand All @@ -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
================================================
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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:
Expand All @@ -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.

Expand Down
24 changes: 21 additions & 3 deletions user_guide_src/source/incoming/routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
=====================

Expand All @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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)
==============================

Expand All @@ -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.
Expand Down