diff --git a/user_guide_src/source/general/helpers.rst b/user_guide_src/source/general/helpers.rst index 88accffd47b3..178744f82368 100644 --- a/user_guide_src/source/general/helpers.rst +++ b/user_guide_src/source/general/helpers.rst @@ -10,11 +10,13 @@ Helper Functions What are Helpers? ***************** -Helpers, as the name suggests, help you with tasks. Each helper file is -simply a collection of functions in a particular category. There are **URL -Helpers**, that assist in creating links, there are **Form Helpers** that help -you create form elements, **Text Helpers** perform various text formatting -routines, **Cookie Helpers** set and read cookies, **File Helpers** help you +Helpers, as the name suggests, help you with tasks. Each helper file is simply a +collection of functions in a particular category. There are +:doc:`URL Helpers <../helpers/url_helper>`, +that assist in creating links, there are :doc:`Form Helpers <../helpers/form_helper>` +that help you create form elements, :doc:`Test Helpers <../helpers/text_helper>` +perform various text formatting routines, :doc:`Cookie Helpers <../helpers/cookie_helper>` +set and read cookies, :doc:`Filesystem Helpers <../helpers/filesystem_helper>` help you deal with files, etc. Unlike most other systems in CodeIgniter, Helpers are not written in an @@ -34,7 +36,7 @@ Helpers are typically stored in your **system/Helpers**, or Loading Helpers *************** -.. note:: The URL helper is always loaded so you do not need to load it yourself. +.. note:: The :doc:`../helpers/url_helper` is always loaded so you do not need to load it yourself. Loading a Helper ================ @@ -43,19 +45,18 @@ Loading a helper file is quite simple using the following method: .. literalinclude:: helpers/001.php -Where ``name`` is the file name of the helper, without the "**.php**" file -extension or the "**_helper**" part. +The above code loads the **name_helper.php** file. .. important:: CodeIgniter helper file names are all lowercase. Therefore, ``helper('Name')`` will not work on case-sensitive file systems such as Linux. -For example, to load the **Cookie Helper** file, which is named +For example, to load the :doc:`../helpers/cookie_helper` file, which is named **cookie_helper.php**, you would do this: .. literalinclude:: helpers/002.php -.. note:: The Helper loading method above does not return a value, so +.. note:: The :php:func:`helper()` function 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 @@ -75,6 +76,19 @@ for details. Or you can :ref:`specify a namespace ` for a helper that you want to load. +Load Order +---------- + +The :php:func:`helper()` function will scan through all defined namespaces and +load in ALL matching helpers of the same name. This allows any module's helpers +to be loaded, as well as any helpers you've created specifically for this application. + +The load order is as follows: + +1. app/Helpers - Files loaded here are always loaded first. +2. {namespace}/Helpers - All namespaces are looped through in the order they are defined. +3. system/Helpers - The base file is loaded last. + Loading Multiple Helpers ======================== @@ -103,12 +117,13 @@ property in Controller instead. See :ref:`Controllers `. 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 in defined namespaces. +By default, CodeIgniter will search for the helper files in all defined namespaces +and load all found files. -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. +If you want to load only a helper in a specific namespace, 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. For this example, assume that we have grouped together all of our Blog-related code into its own namespace, ``Example\Blog``. The files exist on our server at @@ -153,11 +168,26 @@ your view files you would do this: Where ``Click Here`` is the name of the link, and ``blog/comments`` is the URI to the controller/method you wish to link to. -******************* +**************** +Creating Helpers +**************** + +Creating Custom Helpers +======================= + +The helper filename is the **helper name** and **_helper.php**. + +For example, to create info helper, you’ll create a file named +**app/Helpers/info_helper.php**, and add a function to the file: + +.. literalinclude:: helpers/008.php + +You can add as many functions as you like to a single helper file. + "Extending" Helpers -******************* +=================== -To "extend" Helpers, create a file in your **app/Helpers/** folder +To "extend" Helpers, create a file in your **app/Helpers** folder with an identical name to the existing Helper. If all you need to do is add some functionality to an existing helper - @@ -178,14 +208,7 @@ functions: .. important:: Do not specify the namespace ``App\Helpers``. -The :php:func:`helper()` function will scan through all PSR-4 namespaces defined in **app/Config/Autoload.php** -and load in ALL matching helpers of the same name. This allows any module's helpers -to be loaded, as well as any helpers you've created specifically for this application. The load order -is as follows: - -1. app/Helpers - Files loaded here are always loaded first. -2. {namespace}/Helpers - All namespaces are looped through in the order they are defined. -3. system/Helpers - The base file is loaded last +See `Load Order`_ for the order in which helper files are loaded. ********* Now What? diff --git a/user_guide_src/source/general/helpers/008.php b/user_guide_src/source/general/helpers/008.php new file mode 100644 index 000000000000..475b4dd85f1a --- /dev/null +++ b/user_guide_src/source/general/helpers/008.php @@ -0,0 +1,12 @@ +