Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 37f4b9caa02783e06dd7c5318200113409a0deb1 / . / user_guide / general / hooks.html
blob: 11de40902401b25692c46fe9e9f96c2b81e3b18c [file] [log] [blame]
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3<head>
4
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<title>Hooks : CodeIgniter User Guide</title>
7
8<style type='text/css' media='all'>@import url('../userguide.css');</style>
9<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
10
11<script type="text/javascript" src="../nav/nav.js"></script>
12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
13<script type="text/javascript" src="../nav/moo.fx.js"></script>
14<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
15
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
19<meta name='author' content='ExpressionEngine Dev Team' />
20<meta name='description' content='CodeIgniter User Guide' />
21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Pascal Kriete1f622292011-04-07 12:06:51 -0400[diff] [blame]31<td><h1>CodeIgniter User Guide Version 2.0.2</h1></td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39<!-- START BREADCRUMB -->
40<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
41<tr>
42<td id="breadcrumb">
43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45Hooks - Extending the Framework Core
46</td>
47<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58<h1>Hooks - Extending the Framework Core</h1>
59
60<p>CodeIgniter's Hooks feature provides a means to tap into and modify the inner workings of the framework without hacking the core files.
61When CodeIgniter runs it follows a specific execution process, diagramed in the <a href="../overview/appflow.html">Application Flow</a> page.
62There may be instances, however, where you'd like to cause some action to take place at a particular stage in the execution process.
63For example, you might want to run a script right before your controllers get loaded, or right after, or you might want to trigger one of
64your own scripts in some other location.
65</p>
66
67<h2>Enabling Hooks</h2>
68
69<p>The hooks feature can be globally enabled/disabled by setting the following item in the <kbd>application/config/config.php</kbd> file:</p>
70
71<code>$config['enable_hooks'] = TRUE;</code>
72
73
74<h2>Defining a Hook</h2>
75
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]76<p>Hooks are defined in <dfn>application/config/hooks.php</dfn> file. Each hook is specified as an array with this prototype:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]77
78<code>
79$hook['pre_controller'] = array(<br />
80&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'class'&nbsp;&nbsp;&nbsp;&nbsp;=> 'MyClass',<br />
81&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'function' => 'Myfunction',<br />
82&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'Myclass.php',<br />
83&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'filepath' => 'hooks',<br />
84&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'params'&nbsp;&nbsp;&nbsp;=> array('beer', 'wine', 'snacks')<br />
85&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);</code>
86
87<p><strong>Notes:</strong><br />The array index correlates to the name of the particular hook point you want to
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]88use. In the above example the hook point is <kbd>pre_controller</kbd>. A list of hook points is found below.
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]89The following items should be defined in your associative hook array:</p>
90
91<ul>
92<li><strong>class</strong>&nbsp; The name of the class you wish to invoke. If you prefer to use a procedural function instead of a class, leave this item blank.</li>
93<li><strong>function</strong>&nbsp; The function name you wish to call.</li>
94<li><strong>filename</strong>&nbsp; The file name containing your class/function.</li>
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]95<li><strong>filepath</strong>&nbsp; The name of the directory containing your script. Note: Your script must be located in a directory INSIDE your <kbd>application</kbd> folder, so the file path is relative to that folder. For example, if your script is located in <dfn>application/hooks</dfn>, you will simply use <samp>hooks</samp> as your filepath. If your script is located in <dfn>application/hooks/utilities</dfn> you will use <samp>hooks/utilities</samp> as your filepath. No trailing slash.</li>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]96<li><strong>params</strong>&nbsp; Any parameters you wish to pass to your script. This item is optional.</li>
97</ul>
98
99
100<h2>Multiple Calls to the Same Hook</h2>
101
102<p>If want to use the same hook point with more then one script, simply make your array declaration multi-dimensional, like this:</p>
103
104<code>
105$hook['pre_controller']<kbd>[]</kbd> = array(<br />
106&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'class'&nbsp;&nbsp;&nbsp;&nbsp;=> 'MyClass',<br />
107&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'function' => 'Myfunction',<br />
108&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'Myclass.php',<br />
109&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'filepath' => 'hooks',<br />
110&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'params'&nbsp;&nbsp;&nbsp;=> array('beer', 'wine', 'snacks')<br />
111&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
112<br />
113$hook['pre_controller']<kbd>[]</kbd> = array(<br />
114&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'class'&nbsp;&nbsp;&nbsp;&nbsp;=> 'MyOtherClass',<br />
115&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'function' => 'MyOtherfunction',<br />
116&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'Myotherclass.php',<br />
117&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'filepath' => 'hooks',<br />
118&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'params'&nbsp;&nbsp;&nbsp;=> array('red', 'yellow', 'blue')<br />
119&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);</code>
120
121<p>Notice the brackets after each array index:</p>
122
123<code>$hook['pre_controller']<kbd>[]</kbd></code>
124
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]125<p>This permits you to have the same hook point with multiple scripts. The order you define your array will be the execution order.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]126
127
128<h2>Hook Points</h2>
129
130<p>The following is a list of available hook points.</p>
131
132<ul>
133 <li><strong>pre_system</strong><br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]134 Called very early during system execution. Only the benchmark and hooks class have been loaded at this point. No routing or other processes have happened.</li>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]135 <li><strong>pre_controller</strong><br />
136 Called immediately prior to any of your controllers being called. All base classes, routing, and security checks have been done.</li>
137 <li><strong>post_controller_constructor</strong><br />
138 Called immediately after your controller is instantiated, but prior to any method calls happening.</li>
139 <li><strong>post_controller</strong><br />
140 Called immediately after your controller is fully executed.</li>
141 <li><strong>display_override</strong><br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]142 Overrides the <dfn>_display()</dfn> function, used to send the finalized page to the web browser at the end of system execution. This permits you to
143 use your own display methodology. Note that you will need to reference the CI superobject with <dfn>$this->CI =&amp; get_instance()</dfn> and then the finalized data will be available by calling <dfn>$this->CI->output->get_output()</dfn></li>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]144 <li><strong>cache_override</strong><br />
Derek Jones37f4b9c2011-07-01 17:56:50 -0500[diff] [blame^]145 Enables you to call your own function instead of the <dfn>_display_cache()</dfn> function in the output class. This permits you to use your own cache display mechanism.</li>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]146 <li><strong>post_system</strong><br />
147 Called after the final rendered page is sent to the browser, at the end of system execution after the finalized data is sent to the browser.</li>
148 </ul>
149</div>
150<!-- END CONTENT -->
151
152
153<div id="footer">
154<p>
155Previous Topic:&nbsp;&nbsp;<a href="core_classes.html">Creating Core Classes</a>
156&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
157<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
158<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
159Next Topic:&nbsp;&nbsp;<a href="autoloader.html">Auto-loading Resources</a>
160</p>
Derek Jones898949f2011-01-28 07:42:16 -0600[diff] [blame]161<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]162</div>
163
164</body>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]165</html>