blob: 71cb8b25ade88385ed01127065d1698aeefa96e1 [file] [log] [blame]
Derek Jones8ede1a22011-10-05 13:34:52 -05001################
2Helper Functions
3################
4
5Helpers, as the name suggests, help you with tasks. Each helper file is
6simply a collection of functions in a particular category. There are URL
7Helpers, that assist in creating links, there are Form Helpers that help
8you create form elements, Text Helpers perform various text formatting
9routines, Cookie Helpers set and read cookies, File Helpers help you
10deal with files, etc.
11
12Unlike most other systems in CodeIgniter, Helpers are not written in an
13Object Oriented format. They are simple, procedural functions. Each
14helper function performs one specific task, with no dependence on other
15functions.
16
17CodeIgniter does not load Helper Files by default, so the first step in
18using a Helper is to load it. Once loaded, it becomes globally available
19in your :doc:`controller <../general/controllers>` and
20:doc:`views <../general/views>`.
21
22Helpers are typically stored in your system/helpers, or
23application/helpers directory. CodeIgniter will look first in your
24application/helpers directory. If the directory does not exist or the
25specified helper is not located there CI will instead look in your
26global system/helpers folder.
27
28Loading a Helper
29================
30
31Loading a helper file is quite simple using the following function::
32
33 $this->load->helper('name');
34
35Where name is the file name of the helper, without the .php file
36extension or the "helper" part.
37
38For example, to load the URL Helper file, which is named
39url_helper.php, you would do this::
40
41 $this->load->helper('url');
42
43A helper can be loaded anywhere within your controller functions (or
44even within your View files, although that's not a good practice), as
45long as you load it before you use it. You can load your helpers in your
46controller constructor so that they become available automatically in
47any function, or you can load a helper in a specific function that needs
48it.
49
50Note: The Helper loading function above does not return a value, so
51don't try to assign it to a variable. Just use it as shown.
52
53Loading Multiple Helpers
54========================
55
56If you need to load more than one helper you can specify them in an
57array, like this::
58
59 $this->load->helper( array('helper1', 'helper2', 'helper3') );
60
61Auto-loading Helpers
62====================
63
64If you find that you need a particular helper globally throughout your
65application, you can tell CodeIgniter to auto-load it during system
66initialization. This is done by opening the
67application/config/autoload.php file and adding the helper to the
68autoload array.
69
70Using a Helper
71==============
72
73Once you've loaded the Helper File containing the function you intend to
74use, you'll call it the way you would a standard PHP function.
75
76For example, to create a link using the anchor() function in one of your
77view files you would do this::
78
79 <?php echo anchor('blog/comments', 'Click Here');?>
80
81Where "Click Here" is the name of the link, and "blog/comments" is the
82URI to the controller/function you wish to link to.
83
84"Extending" Helpers
85===================
86
87To "extend" Helpers, create a file in your application/helpers/ folder
88with an identical name to the existing Helper, but prefixed with MY\_
89(this item is configurable. See below.).
90
91If all you need to do is add some functionality to an existing helper -
92perhaps add a function or two, or change how a particular helper
93function operates - then it's overkill to replace the entire helper with
94your version. In this case it's better to simply "extend" the Helper.
95The term "extend" is used loosely since Helper functions are procedural
96and discrete and cannot be extended in the traditional programmatic
97sense. Under the hood, this gives you the ability to add to the
98functions a Helper provides, or to modify how the native Helper
99functions operate.
100
101For example, to extend the native Array Helper you'll create a file
102named application/helpers/MY_array_helper.php, and add or override
103functions::
104
Derek Jonesa1360ef2011-10-05 17:22:53 -0500105 // any_in_array() is not in the Array Helper, so it defines a new function
106 function any_in_array($needle, $haystack)
107 {
108 $needle = (is_array($needle)) ? $needle : array($needle);
109
110 foreach ($needle as $item)
111 {
112 if (in_array($item, $haystack))
113 {
114 return TRUE;
115 }
116 }
117
118 return FALSE;
119 }
120
121 // random_element() is included in Array Helper, so it overrides the native function
122 function random_element($array)
123 {
124 shuffle($array);
125 return array_pop($array);
126 }
Derek Jones8ede1a22011-10-05 13:34:52 -0500127
128Setting Your Own Prefix
129-----------------------
130
131The filename prefix for "extending" Helpers is the same used to extend
132libraries and Core classes. To set your own prefix, open your
133application/config/config.php file and look for this item::
134
135 $config['subclass_prefix'] = 'MY_';
136
137Please note that all native CodeIgniter libraries are prefixed with CI\_
138so DO NOT use that as your prefix.
139
140Now What?
141=========
142
143In the Table of Contents you'll find a list of all the available Helper
144Files. Browse each one to see what they do.