Skip to content
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.

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

docs: fix helper loading #8084

Merged
merged 5 commits into from
Oct 25, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion system/Common.php
Original file line number Diff line number Diff line change
Expand Up @@ -579,7 +579,7 @@ function function_usable(string $functionName): bool
if (! function_exists('helper')) {
/**
* Loads a helper file into memory. Supports namespaced helpers,
* both in and out of the 'helpers' directory of a namespaced directory.
* both in and out of the 'Helpers' directory of a namespaced directory.
*
* Will load ALL helpers of the matching name, in the following order:
* 1. app/Helpers
Expand Down
20 changes: 15 additions & 5 deletions user_guide_src/source/concepts/autoloader.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,10 @@ Configuration
Initial configuration is done in **app/Config/Autoload.php**. This file contains two primary
arrays: one for the classmap, and one for PSR-4 compatible namespaces.

.. _autoloader-namespaces:

Namespaces
**********
==========

The recommended method for organizing your classes is to create one or more namespaces for your
application's files. This is most important for any business-logic related classes, entity classes,
Expand All @@ -55,11 +57,19 @@ those classes can be found in:
The key of each row is the namespace itself. This does not need a trailing back slash.
The value is the location to the directory the classes can be found in.

.. note:: You can check the namespace configuration by ``spark namespaces`` command:
.. _confirming-namespaces:

Confirming Namespaces
=====================

You can check the namespace configuration by ``spark namespaces`` command:

.. code-block:: console

.. code-block:: console
php spark namespaces

php spark namespaces
Application Namespace
=====================

By default, the application directory is namespace to the ``App`` namespace. You must namespace the controllers,
libraries, or models in the application directory, and they will be found under the ``App`` namespace.
Expand All @@ -77,7 +87,7 @@ You will need to modify any existing files that are referencing the current name
namespace has changed.

Classmap
********
========

The classmap is used extensively by CodeIgniter to eke the last ounces of performance out of the system
by not hitting the file-system with extra ``is_file()`` calls. You can use the classmap to link to
Expand Down
41 changes: 29 additions & 12 deletions user_guide_src/source/general/helpers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,17 +28,17 @@ in your :doc:`controller <../incoming/controllers>` and
:doc:`views <../outgoing/views>`.

Helpers are typically stored in your **system/Helpers**, or
**app/Helpers** directory. CodeIgniter will look first in your
**app/Helpers** directory. If the directory does not exist or the
specified helper is not located there CI will instead look in your
global **system/Helpers** directory.
**app/Helpers** directory.

****************
Loading a Helper
****************
***************
Loading Helpers
***************

.. note:: The URL helper is always loaded so you do not need to load it yourself.

Loading a Helper
================

Loading a helper file is quite simple using the following method:

.. literalinclude:: helpers/001.php
Expand All @@ -58,6 +58,23 @@ For example, to load the **Cookie Helper** file, which is named
.. note:: The Helper loading method above does not return a value, so
don't try to assign it to a variable. Just use it as shown.

Auto-Discovery and Composer Packages
------------------------------------

By default, CodeIgniter will search for the helper files in all defined namespaces
by :ref:`auto-discovery`.
You can check your defined namespaces by the spark command. See :ref:`confirming-namespaces`.

If you use many Composer packages, you will have many defined namespaces.
CodeIgniter will scan all namespaces by default.

To avoid wasting time scanning for irrelevant Composer packages, you can manually
specify packages for Auto-Discovery. See :ref:`modules-specify-composer-packages`
for details.

Or you can :ref:`specify a namespace <helpers-loading-from-specified-namespace>`
for a helper that you want to load.

Loading Multiple Helpers
========================

Expand All @@ -81,14 +98,14 @@ it.
However if you want to load in your controller constructor, you can use the ``$helpers``
property in Controller instead. See :ref:`Controllers <controllers-helpers>`.

.. _helpers-loading-from-non-standard-locations:
.. _helpers-loading-from-specified-namespace:

Loading from Non-standard Locations
===================================
Loading from Specified Namespace
================================

Helpers can be loaded from directories outside of **app/Helpers** and
**system/Helpers**, as long as that path can be found through a namespace that
has been set up within the PSR-4 section of the :doc:`Autoloader config file <../concepts/autoloader>`.
**system/Helpers**, as long as that path can be found in defined namespaces.

You would prefix the name of the Helper with the namespace that it can be located
in. Within that namespaced directory, the loader expects it to live within a
sub-directory named **Helpers**. An example will help understand this.
Expand Down
7 changes: 4 additions & 3 deletions user_guide_src/source/general/modules.rst
Original file line number Diff line number Diff line change
Expand Up @@ -240,12 +240,13 @@ For Windows:
Helpers
=======

Helpers will be automatically discovered within defined namespaces when using the ``helper()`` function, as long as it
is within the namespaces **Helpers** directory:
Helpers will be automatically discovered within defined namespaces when using the
:php:func:`helper()` function, as long as it is within the namespaces **Helpers**
directory:

.. literalinclude:: modules/009.php

You can specify namespaces. See :ref:`helpers-loading-from-non-standard-locations` for details.
You can specify namespaces. See :ref:`helpers-loading-from-specified-namespace` for details.

Language Files
==============
Expand Down
1 change: 1 addition & 0 deletions user_guide_src/source/helpers/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ Helpers
#######

Helpers are collections of useful procedural functions.
See also :doc:`../general/helpers`.

.. toctree::
:glob:
Expand Down
Loading