]>
Commit | Line | Data |
---|---|---|
59c06b17 CS |
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>Controllers : 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> | |
31 | <td><h1>CodeIgniter User Guide Version 2.1.3</h1></td> | |
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> › | |
44 | <a href="../index.html">User Guide Home</a> › | |
45 | Controllers | |
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 <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <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>Controllers</h1> | |
59 | ||
60 | <p>Controllers are the heart of your application, as they determine how HTTP requests should be handled.</p> | |
61 | ||
62 | ||
63 | <ul> | |
64 | <li><a href="#what">What is a Controller?</a></li> | |
65 | <li><a href="#hello">Hello World</a></li> | |
66 | <li><a href="#functions">Functions</a></li> | |
67 | <li><a href="#passinguri">Passing URI Segments to Your Functions</a></li> | |
68 | <li><a href="#default">Defining a Default Controller</a></li> | |
69 | <li><a href="#remapping">Remapping Function Calls</a></li> | |
70 | <li><a href="#output">Controlling Output Data</a></li> | |
71 | <li><a href="#private">Private Functions</a></li> | |
72 | <li><a href="#subfolders">Organizing Controllers into Sub-folders</a></li> | |
73 | <li><a href="#constructors">Class Constructors</a></li> | |
74 | <li><a href="#reserved">Reserved Function Names</a></li> | |
75 | </ul> | |
76 | ||
77 | ||
78 | <a name="what"></a> | |
79 | <h2>What is a Controller?</h2> | |
80 | ||
81 | <p><dfn>A Controller is simply a class file that is named in a way that can be associated with a URI.</dfn></p> | |
82 | ||
83 | <p>Consider this URI:</p> | |
84 | ||
85 | <code>example.com/index.php/<var>blog</var>/</code> | |
86 | ||
87 | <p>In the above example, CodeIgniter would attempt to find a controller named <dfn>blog.php</dfn> and load it.</p> | |
88 | ||
89 | <p><strong>When a controller's name matches the first segment of a URI, it will be loaded.</strong></p> | |
90 | ||
91 | <a name="hello"></a> | |
92 | <h2>Let's try it: Hello World!</h2> | |
93 | ||
94 | <p>Let's create a simple controller so you can see it in action. Using your text editor, create a file called <dfn>blog.php</dfn>, and put the following code in it:</p> | |
95 | ||
96 | ||
97 | <textarea class="textarea" style="width:100%" cols="50" rows="10"> | |
98 | <?php | |
99 | class Blog extends CI_Controller { | |
100 | ||
101 | public function index() | |
102 | { | |
103 | echo 'Hello World!'; | |
104 | } | |
105 | } | |
106 | ?> | |
107 | </textarea> | |
108 | ||
109 | ||
110 | ||
111 | <p>Then save the file to your <dfn>application/controllers/</dfn> folder.</p> | |
112 | ||
113 | <p>Now visit the your site using a URL similar to this:</p> | |
114 | ||
115 | <code>example.com/index.php/<var>blog</var>/</code> | |
116 | ||
117 | <p>If you did it right, you should see <samp>Hello World!</samp>.</p> | |
118 | ||
119 | <p>Note: Class names must start with an uppercase letter. In other words, this is valid:</p> | |
120 | ||
121 | <code><?php<br /> | |
122 | class <var>Blog</var> extends CI_Controller {<br /> | |
123 | <br /> | |
124 | }<br /> | |
125 | ?></code> | |
126 | ||
127 | <p>This is <strong>not</strong> valid:</p> | |
128 | ||
129 | <code><?php<br /> | |
130 | class <var>blog</var> extends CI_Controller {<br /> | |
131 | <br /> | |
132 | }<br /> | |
133 | ?></code> | |
134 | ||
135 | <p>Also, always make sure your controller <dfn>extends</dfn> the parent controller class so that it can inherit all its functions.</p> | |
136 | ||
137 | ||
138 | ||
139 | <a name="functions"></a> | |
140 | <h2>Functions</h2> | |
141 | ||
142 | <p>In the above example the function name is <dfn>index()</dfn>. The "index" function is always loaded by default if the | |
143 | <strong>second segment</strong> of the URI is empty. Another way to show your "Hello World" message would be this:</p> | |
144 | ||
145 | <code>example.com/index.php/<var>blog</var>/<samp>index</samp>/</code> | |
146 | ||
147 | <p><strong>The second segment of the URI determines which function in the controller gets called.</strong></p> | |
148 | ||
149 | <p>Let's try it. Add a new function to your controller:</p> | |
150 | ||
151 | ||
152 | <textarea class="textarea" style="width:100%" cols="50" rows="15"> | |
153 | <?php | |
154 | class Blog extends CI_Controller { | |
155 | ||
156 | public function index() | |
157 | { | |
158 | echo 'Hello World!'; | |
159 | } | |
160 | ||
161 | public function comments() | |
162 | { | |
163 | echo 'Look at this!'; | |
164 | } | |
165 | } | |
166 | ?> | |
167 | </textarea> | |
168 | ||
169 | <p>Now load the following URL to see the <dfn>comment</dfn> function:</p> | |
170 | ||
171 | <code>example.com/index.php/<var>blog</var>/<samp>comments</samp>/</code> | |
172 | ||
173 | <p>You should see your new message.</p> | |
174 | ||
175 | <a name="passinguri"></a> | |
176 | <h2>Passing URI Segments to your Functions</h2> | |
177 | ||
178 | <p>If your URI contains more then two segments they will be passed to your function as parameters.</p> | |
179 | ||
180 | <p>For example, lets say you have a URI like this:</p> | |
181 | ||
182 | <code>example.com/index.php/<var>products</var>/<samp>shoes</samp>/<kbd>sandals</kbd>/<dfn>123</dfn></code> | |
183 | ||
184 | <p>Your function will be passed URI segments 3 and 4 ("sandals" and "123"):</p> | |
185 | ||
186 | <code> | |
187 | <?php<br /> | |
188 | class Products extends CI_Controller {<br /> | |
189 | <br /> | |
190 | public function shoes($sandals, $id)<br /> | |
191 | {<br /> | |
192 | echo $sandals;<br /> | |
193 | echo $id;<br /> | |
194 | }<br /> | |
195 | }<br /> | |
196 | ?> | |
197 | </code> | |
198 | ||
199 | <p class="important"><strong>Important:</strong> If you are using the <a href="routing.html">URI Routing</a> feature, the segments | |
200 | passed to your function will be the re-routed ones.</p> | |
201 | ||
202 | ||
203 | <a name="default"></a> | |
204 | <h2>Defining a Default Controller</h2> | |
205 | ||
206 | <p>CodeIgniter can be told to load a default controller when a URI is not present, | |
207 | as will be the case when only your site root URL is requested. To specify a default controller, open | |
208 | your <dfn>application/config/routes.php</dfn> file and set this variable:</p> | |
209 | ||
210 | <code>$route['default_controller'] = '<var>Blog</var>';</code> | |
211 | ||
212 | <p>Where <var>Blog</var> is the name of the controller class you want used. If you now load your main index.php file without | |
213 | specifying any URI segments you'll see your Hello World message by default.</p> | |
214 | ||
215 | ||
216 | ||
217 | <a name="remapping"></a> | |
218 | <h2>Remapping Function Calls</h2> | |
219 | ||
220 | <p>As noted above, the second segment of the URI typically determines which function in the controller gets called. | |
221 | CodeIgniter permits you to override this behavior through the use of the <kbd>_remap()</kbd> function:</p> | |
222 | ||
223 | <code>public function _remap()<br /> | |
224 | {<br /> | |
225 | // Some code here...<br /> | |
226 | }</code> | |
227 | ||
228 | <p class="important"><strong>Important:</strong> If your controller contains a function named <kbd>_remap()</kbd>, it will <strong>always</strong> | |
229 | get called regardless of what your URI contains. It overrides the normal behavior in which the URI determines which function is called, | |
230 | allowing you to define your own function routing rules.</p> | |
231 | ||
232 | <p>The overridden function call (typically the second segment of the URI) will be passed as a parameter to the <kbd>_remap()</kbd> function:</p> | |
233 | ||
234 | <code>public function _remap(<var>$method</var>)<br /> | |
235 | {<br /> | |
236 | if ($method == 'some_method')<br /> | |
237 | {<br /> | |
238 | $this->$method();<br /> | |
239 | }<br /> | |
240 | else<br /> | |
241 | {<br /> | |
242 | $this->default_method();<br /> | |
243 | }<br /> | |
244 | }</code> | |
245 | ||
246 | <p>Any extra segments after the method name are passed into <kbd>_remap()</kbd> as an optional second parameter. This array can be used in combination with PHP's <a href="http://php.net/call_user_func_array">call_user_func_array</a> to emulate CodeIgniter's default behavior.</p> | |
247 | ||
248 | <code>public function _remap($method, $params = array())<br /> | |
249 | {<br /> | |
250 | $method = 'process_'.$method;<br /> | |
251 | if (method_exists($this, $method))<br /> | |
252 | {<br /> | |
253 | return call_user_func_array(array($this, $method), $params);<br /> | |
254 | }<br /> | |
255 | show_404();<br /> | |
256 | }</code> | |
257 | ||
258 | ||
259 | <a name="output"></a> | |
260 | <h2>Processing Output</h2> | |
261 | ||
262 | <p>CodeIgniter has an output class that takes care of sending your final rendered data to the web browser automatically. More information on this can be found in the | |
263 | <a href="views.html">Views</a> and <a href="../libraries/output.html">Output class</a> pages. In some cases, however, you might want to | |
264 | post-process the finalized data in some way and send it to the browser yourself. CodeIgniter permits you to | |
265 | add a function named <dfn>_output()</dfn> to your controller that will receive the finalized output data.</p> | |
266 | ||
267 | <p><strong>Important:</strong> If your controller contains a function named <kbd>_output()</kbd>, it will <strong>always</strong> | |
268 | be called by the output class instead of echoing the finalized data directly. The first parameter of the function will contain the finalized output.</p> | |
269 | ||
270 | <p>Here is an example:</p> | |
271 | ||
272 | <code> | |
273 | public function _output($output)<br /> | |
274 | {<br /> | |
275 | echo $output;<br /> | |
276 | }</code> | |
277 | ||
278 | <p class="important">Please note that your <dfn>_output()</dfn> function will receive the data in its finalized state. Benchmark and memory usage data will be rendered, | |
279 | cache files written (if you have caching enabled), and headers will be sent (if you use that <a href="../libraries/output.html">feature</a>) | |
280 | before it is handed off to the _output() function.<br /> | |
281 | <br /> | |
282 | To have your controller's output cached properly, its <dfn>_output()</dfn> method can use:<br /> | |
283 | ||
284 | <code>if ($this->output->cache_expiration > 0)<br /> | |
285 | {<br /> | |
286 | $this->output->_write_cache($output);<br /> | |
287 | }</code> | |
288 | ||
289 | If you are using this feature the page execution timer and memory usage stats might not be perfectly accurate | |
290 | since they will not take into acccount any further processing you do. For an alternate way to control output <em>before</em> any of the final processing is done, please see | |
291 | the available methods in the <a href="../libraries/output.html">Output Class</a>.</p> | |
292 | ||
293 | <a name="private"></a> | |
294 | <h2>Private Functions</h2> | |
295 | ||
296 | ||
297 | <p>In some cases you may want certain functions hidden from public access. To make a function private, simply add an | |
298 | underscore as the name prefix and it will not be served via a URL request. For example, if you were to have a function like this:</p> | |
299 | ||
300 | <code> | |
301 | private function _utility()<br /> | |
302 | {<br /> | |
303 | // some code<br /> | |
304 | }</code> | |
305 | ||
306 | <p>Trying to access it via the URL, like this, will not work:</p> | |
307 | ||
308 | <code>example.com/index.php/<var>blog</var>/<samp>_utility</samp>/</code> | |
309 | ||
310 | ||
311 | ||
312 | <a name="subfolders"></a> | |
313 | <h2>Organizing Your Controllers into Sub-folders</h2> | |
314 | ||
315 | <p>If you are building a large application you might find it convenient to organize your controllers into sub-folders. CodeIgniter permits you to do this.</p> | |
316 | ||
317 | <p>Simply create folders within your <dfn>application/controllers</dfn> directory and place your controller classes within them.</p> | |
318 | ||
319 | <p><strong>Note:</strong> When using this feature the first segment of your URI must specify the folder. For example, lets say you have a controller | |
320 | located here:</p> | |
321 | ||
322 | <code>application/controllers/<kbd>products</kbd>/shoes.php</code> | |
323 | ||
324 | <p>To call the above controller your URI will look something like this:</p> | |
325 | ||
326 | <code>example.com/index.php/products/shoes/show/123</code> | |
327 | ||
328 | <p>Each of your sub-folders may contain a default controller which will be | |
329 | called if the URL contains only the sub-folder. Simply name your default controller as specified in your | |
330 | <dfn>application/config/routes.php</dfn> file</p> | |
331 | ||
332 | ||
333 | <p>CodeIgniter also permits you to remap your URIs using its <a href="routing.html">URI Routing</a> feature.</p> | |
334 | ||
335 | ||
336 | <h2><a name="constructors"></a>Class Constructors</h2> | |
337 | ||
338 | ||
339 | <p>If you intend to use a constructor in any of your Controllers, you <strong>MUST</strong> place the following line of code in it:</p> | |
340 | ||
341 | <code>parent::__construct();</code> | |
342 | ||
343 | <p>The reason this line is necessary is because your local constructor will be overriding the one in the parent controller class so we need to manually call it.</p> | |
344 | ||
345 | <code> | |
346 | <?php<br /> | |
347 | class <kbd>Blog</kbd> extends CI_Controller {<br /> | |
348 | <br /> | |
349 | public function <kbd>__construct()</kbd><br /> | |
350 | {<br /> | |
351 | <var>parent::__construct();</var><br /> | |
352 | // Your own constructor code<br /> | |
353 | }<br /> | |
354 | }<br /> | |
355 | ?></code> | |
356 | ||
357 | <p>Constructors are useful if you need to set some default values, or run a default process when your class is instantiated. | |
358 | Constructors can't return a value, but they can do some default work.</p> | |
359 | ||
360 | <a name="reserved"></a> | |
361 | <h2>Reserved Function Names</h2> | |
362 | ||
363 | <p>Since your controller classes will extend the main application controller you | |
364 | must be careful not to name your functions identically to the ones used by that class, otherwise your local functions | |
365 | will override them. See <a href="reserved_names.html">Reserved Names</a> for a full list.</p> | |
366 | ||
367 | <h2>That's it!</h2> | |
368 | ||
369 | <p>That, in a nutshell, is all there is to know about controllers.</p> | |
370 | ||
371 | ||
372 | ||
373 | </div> | |
374 | <!-- END CONTENT --> | |
375 | ||
376 | ||
377 | <div id="footer"> | |
378 | <p> | |
379 | Previous Topic: <a href="urls.html">CodeIgniter URLs</a> | |
380 | · | |
381 | <a href="#top">Top of Page</a> · | |
382 | <a href="../index.html">User Guide Home</a> · | |
383 | Next Topic: <a href="reserved_names.html">Reserved Names</a></p> | |
384 | <p><a href="http://codeigniter.com">CodeIgniter</a> · Copyright © 2006 - 2012 · <a href="http://ellislab.com/">EllisLab, Inc.</a></p> | |
385 | </div> | |
386 | ||
387 | </body> | |
388 | </html> |