Merge pull request #8294 from kenjis/docs-helpers

docs: improve helpers

Author: kenjis

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 <helpers-loading-from-specified-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 <controllers-helpers>`.
 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?

user_guide_src/source/general/helpers/008.php

@@ -0,0 +1,12 @@
+<?php
+
+// app/Helpers/info_helper.php
+use CodeIgniter\CodeIgniter;
+
+/**
+ * Returns CodeIgniter's version.
+ */
+function ci_version(): string
+{
+    return CodeIgniter::CI_VERSION;
+}