Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / a634e56d86b965df334e4a431fb0586565ade7a6 / . / user_guide / general / hooks.html
blob: 33d343d822fb6e9dd85cb7f8a1529fbb9a7889b6 [file] [log] [blame]
adminb0dd10f2006-08-25 17:25:49 +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>
3<head>
4
5<title>Code Igniter User Guide</title>
6
7<style type='text/css' media='all'>@import url('../userguide.css');</style>
8<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
9
10<script type="text/javascript" src="../scripts/nav.js"></script>
11<script type="text/javascript" src="../scripts/prototype.lite.js"></script>
12<script type="text/javascript" src="../scripts/moo.fx.js"></script>
13<script type="text/javascript">
14window.onload = function() {
15 myHeight = new fx.Height('nav', {duration: 400});
16 myHeight.hide();
17}
18</script>
19
20<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
21<meta http-equiv='expires' content='-1' />
22<meta http-equiv= 'pragma' content='no-cache' />
23<meta name='robots' content='all' />
24<meta name='author' content='Rick Ellis' />
25<meta name='description' content='Code Igniter User Guide' />
26
27</head>
28<body>
29
30<!-- START NAVIGATION -->
31<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
32<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
33<div id="masthead">
34<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
35<tr>
36<td><h1>Code Igniter User Guide Version 1.4.0</h1></td>
37<td id="breadcrumb_right"><a href="../toc.html">Full Table of Contents</a></td>
38</tr>
39</table>
40</div>
41<!-- END NAVIGATION -->
42
43
44<!-- START BREADCRUMB -->
45<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
46<tr>
47<td id="breadcrumb">
48<a href="http://www.codeigniter.com/">Code Igniter Home</a> &nbsp;&#8250;&nbsp;
49<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
50Hooks - Extending the Framework Core
51</td>
52<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="www.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>
53</tr>
54</table>
55<!-- END BREADCRUMB -->
56
57<br clear="all" />
58
59
60<!-- START CONTENT -->
61<div id="content">
62
63<h1>Hooks - Extending the Framework Core</h1>
64
65<p>Code Igniter's Hooks feature provides a means to tap into and modify the inner workings of the framework without hacking the core files.
66When Code Igniter runs it follows a specific execution process, diagramed in the <a href="../overview/appflow.html">Application Flow</a> page.
67There may be instances, however, where you'd like to cause some action to take place at a particular stage in the execution process.
68For 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
69your own scripts in some other location.
70</p>
71
72
73<h2>Defining a Hook</h2>
74
75<p>Hooks are defined in <dfn>application/config/hooks.php</dfn> file. Each hook is specified as an array with this prototype:</p>
76
77<code>
78$hook['pre_controller'] = array(<br />
79&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 />
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;'function' => 'Myfunction',<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;'filename' => 'Myclass.php',<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;'filepath' => 'hooks',<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;'params'&nbsp;&nbsp;&nbsp;=> array('beer', 'wine', 'snacks')<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;);</code>
85
86<p><strong>Notes:</strong><br />The array index correlates to the name of the particular hook point you want to
87use. In the above example the hook point is <kbd>pre_controller</kbd>. A list of hook points is found below.
88The following items should be defined in your associative hook array:</p>
89
90<ul>
91<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>
92<li><strong>function</strong>&nbsp; The function name you wish to call.</li>
93<li><strong>filename</strong>&nbsp; The file name containing your class/function.</li>
94<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>
95<li><strong>params</strong>&nbsp; Any parameters you wish to pass to your script. This item is optional.</li>
96</ul>
97
98
99<h2>Multiple Calls to the Same Hook</h2>
100
101<p>If want to use the same hook point with more then one script, simply make your array declaration multi-dimensional, like this:
102
103<code>
104$hook['pre_controller']<kbd>[]</kbd> = array(<br />
105&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 />
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;'function' => 'Myfunction',<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;'filename' => 'Myclass.php',<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;'filepath' => 'hooks',<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;'params'&nbsp;&nbsp;&nbsp;=> array('beer', 'wine', 'snacks')<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;);<br />
111<br />
112$hook['pre_controller']<kbd>[]</kbd> = array(<br />
113&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 />
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;'function' => 'MyOtherfunction',<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;'filename' => 'Myotherclass.php',<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;'filepath' => 'hooks',<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;'params'&nbsp;&nbsp;&nbsp;=> array('red', 'yellow', 'blue')<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;);</code>
119
120<p>Notice the brackets after each array index:</p>
121
122<code>$hook['pre_controller']<kbd>[]</kbd></code>
123
124<p>This permits you to the same hook point with multiple scripts. The order you define your array will be the execution order.</p>
125
126
127<h2>Hook Points</h2>
128
129The following is a list of available hook points.</p>
130
131<ul>
132
133<li><strong>pre_system</strong><br />
134Called 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>
135
136<li><strong>pre_controller</strong><br />
137Called immediately prior to any of your controllers being called. All base classes, routing, and security checks have been done.</li>
138
139<li><strong>post_controller</strong><br />
140Called immediately after the controller is called.</li>
141
142<li><strong>display_override</strong><br />
143Overrides 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
144use your own display methodology. Note that the finalized data will be available by calling <dfn>$this->output->get_output()</dfn></li>
145
146<li><strong>cache_override</strong><br />
147Enables 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>
148
149<li><strong>scaffolding_override</strong><br />
150Permits a scaffolding request to trigger your own script instead.</li>
151
152<li><strong>post_system</strong><br />
153Called 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>
154
155
156</ul>
157
158
159
160
161
162
163
164
165
166
167
168</div>
169<!-- END CONTENT -->
170
171
172<div id="footer">
173<p>
admina634e562006-08-25 22:19:55 +0000[diff] [blame^]174Previous Topic:&nbsp;&nbsp;<a href="core_classes.html">Creating Core Classes</a>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]175&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
176<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
177<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
admina634e562006-08-25 22:19:55 +0000[diff] [blame^]178Next Topic:&nbsp;&nbsp;<a href="autoloader.html">Auto-loading Resources</a>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]179<p>
180<p><a href="http://www.codeigniter.com">Code Igniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 &nbsp;&middot;&nbsp; <a href="http://www.pmachine.com">pMachine, Inc.</a></p>
181</div>
182
183</body>
184</html>