Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 92bb3e6ad6083b13213c4c3e71d0fbb6a7f83971 / . / user_guide / general / controllers.html
blob: 4c0c506af7afe9bb29bf3d3f9896a970136ad6c7 [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">
Derek Allardafd99ac2008-01-19 19:59:14 +0000[diff] [blame]2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]3<head>
4
Derek Jonesfd93d222008-05-06 15:18:50 +0000[diff] [blame]5<title>Controllers : CodeIgniter User Guide</title>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]10<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]11<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]12<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]13<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]14
15<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +0000[diff] [blame]19<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]20<meta name='description' content='CodeIgniter User Guide' />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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.jpg" width="153" height="44" 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>
Derek Jones6b7b11f2008-05-06 16:07:27 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.2</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45Controllers
46</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]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>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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>
admin2c676ef2006-09-21 16:54:44 +0000[diff] [blame]67<li><a href="#passinguri">Passing URI Segments to Your Functions</a></li>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]68<li><a href="#default">Defining a Default Controller</a></li>
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]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>
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]72<li><a href="#subfolders">Organizing Controllers into Sub-folders</a></li>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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>www.your-site.com/index.php/<var>blog</var>/</code>
86
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]87<p>In the above example, CodeIgniter would attempt to find a controller named <dfn>blog.php</dfn> and load it.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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:&nbsp; 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
99class Blog extends Controller {
100
101 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>www.your-site.com/index.php/<var>blog</var>/</code>
116
117<p>If you did it right, you should see <samp>Hello World!</samp>.</p>
118
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]119<p>Note: Class names must start with an uppercase letter. In other words, this is valid:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]120
121<code>&lt;?php<br />
122class <var>Blog</var> extends Controller {<br />
123<br />
124}<br />
125?&gt;</code>
126
127<p>This is <strong>not</strong> valid:</p>
128
129<code>&lt;?php<br />
130class <var>blog</var> extends Controller {<br />
131<br />
132}<br />
133?&gt;</code>
134
admine334c472006-10-21 19:44:22 +0000[diff] [blame]135<p>Also, always make sure your controller <dfn>extends</dfn> the parent controller class so that it can inherit all its functions.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]136
137
138
139<a name="functions"></a>
140<h2>Functions</h2>
141
admine334c472006-10-21 19:44:22 +0000[diff] [blame]142<p>In the above example the function name is <dfn>index()</dfn>. The "index" function is always loaded by default if the
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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>www.your-site.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
154class Blog extends Controller {
155
156 function index()
157 {
158 echo 'Hello World!';
159 }
160
161 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>www.your-site.com/index.php/<var>blog</var>/<samp>comments</samp>/</code>
172
173<p>You should see your new message.</p>
174
admin2c676ef2006-09-21 16:54:44 +0000[diff] [blame]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
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]180<p>For example, lets say you have a URI like this:</p>
admin2c676ef2006-09-21 16:54:44 +0000[diff] [blame]181
182<code>www.your-site.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&lt;?php<br />
188class Products extends Controller {<br />
189<br />
190&nbsp;&nbsp;&nbsp;&nbsp;function shoes($sandals, $id)<br />
191&nbsp;&nbsp;&nbsp;&nbsp;{<br />
192&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo $sandals;<br />
193&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo $id;<br />
194&nbsp;&nbsp;&nbsp;&nbsp;}<br />
195}<br />
196?&gt;
197</code>
198
199<p class="important"><strong>Important:</strong>&nbsp; If you are using the <a href="routing.html">URI Routing</a> feature, the segments
200passed to your function will be the re-routed ones.</p>
201
202
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]203<a name="default"></a>
204<h2>Defining a Default Controller</h2>
205
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]206<p>CodeIgniter can be told to load a default controller when a URI is not present,
admine334c472006-10-21 19:44:22 +0000[diff] [blame]207as will be the case when only your site root URL is requested. To specify a default controller, open
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]208your <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
213specifying any URI segments you'll see your Hello World message by default.</p>
214
215
admin1cf89aa2006-09-03 18:24:39 +0000[diff] [blame]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.
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]221CodeIgniter permits you to override this behavior through the use of the <kbd>_remap()</kbd> function:</p>
admin1cf89aa2006-09-03 18:24:39 +0000[diff] [blame]222
223<code>function _remap()<br />
224{<br />
225&nbsp;&nbsp;&nbsp;&nbsp;// Some code here...<br />
226}</code>
227
admine334c472006-10-21 19:44:22 +0000[diff] [blame]228<p class="important"><strong>Important:</strong>&nbsp; If your controller contains a function named <kbd>_remap()</kbd>, it will <strong>always</strong>
229get called regardless of what your URI contains. It overrides the normal behavior in which the URI determines which function is called,
admin1cf89aa2006-09-03 18:24:39 +0000[diff] [blame]230allowing you to define your own function routing rules.</p>
231
admin2c676ef2006-09-21 16:54:44 +0000[diff] [blame]232<p>The overridden function call (typically the second segment of the URI) will be passed as a parameter the <kbd>_remap()</kbd> function:</p>
admin1cf89aa2006-09-03 18:24:39 +0000[diff] [blame]233
234<code>function _remap(<var>$method</var>)<br />
235{<br />
236&nbsp;&nbsp;&nbsp;&nbsp;if ($method == 'some_method')<br />
237&nbsp;&nbsp;&nbsp;&nbsp;{<br />
238&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->$method();<br />
239&nbsp;&nbsp;&nbsp;&nbsp;}<br />
240&nbsp;&nbsp;&nbsp;&nbsp;else<br />
241&nbsp;&nbsp;&nbsp;&nbsp;{<br />
242&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->default_method();<br />
243&nbsp;&nbsp;&nbsp;&nbsp;}<br />
244}</code>
245
246
247
248
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]249
250<a name="output"></a>
251<h2>Processing Output</h2>
252
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]253<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
admine334c472006-10-21 19:44:22 +0000[diff] [blame]254<a href="views.html">Views</a> and <a href="../libraries/output.html">Output class</a> pages. In some cases, however, you might want to
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]255post-process the finalized data in some way and send it to the browser yourself. CodeIgniter permits you to
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]256add a function named <dfn>_output()</dfn> to your controller that will receive the finalized output data.</p>
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]257
admine334c472006-10-21 19:44:22 +0000[diff] [blame]258<p><strong>Important:</strong>&nbsp; If your controller contains a function named <kbd>_output()</kbd>, it will <strong>always</strong>
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]259be called by the output class instead of echoing the finalized data directly. The first parameter of the function will contain the finalized output.</p>
260
261<p>Here is an example:</p>
262
263<code>
264function _output($output)<br />
265{<br />
266&nbsp;&nbsp;&nbsp;&nbsp;echo $output;<br />
267}</code>
268
adminbaa58182006-09-23 03:59:30 +0000[diff] [blame]269<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,
Derek Allard4b7d19d2007-07-11 19:44:50 +0000[diff] [blame]270cache files written (if you have caching enabled), and headers will be sent (if you use that <a href="../libraries/output.html">feature</a>)
adminbaa58182006-09-23 03:59:30 +0000[diff] [blame]271before it is handed off to the _output() function. If you are using this feature the page execution timer and memory usage stats might not be perfectly accurate
272since 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
Derek Allard4b7d19d2007-07-11 19:44:50 +0000[diff] [blame]273the available methods in the <a href="../libraries/output.html">Output Class</a>.</p>
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]274
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]275<a name="private"></a>
276<h2>Private Functions</h2>
277
adminc1fa0742006-09-21 23:50:23 +0000[diff] [blame]278
admin1cf89aa2006-09-03 18:24:39 +0000[diff] [blame]279<p>In some cases you may want certain functions hidden from public access. To make a function private, simply add an
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]280underscore 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>
281
282<code>
283function _utility()<br />
284{<br />
285&nbsp;&nbsp;// some code<br />
286}</code>
287
288<p>Trying to access it via the URL, like this, will not work:</p>
289
290<code>www.your-site.com/index.php/<var>blog</var>/<samp>_utility</samp>/</code>
291
292
293
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]294<a name="subfolders"></a>
295<h2>Organizing Your Controllers into Sub-folders</h2>
296
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]297<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>
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]298
299<p>Simply create folders within your <dfn>application/controllers</dfn> directory and place your controller classes within them.</p>
300
admin1082bdd2006-08-27 19:32:02 +0000[diff] [blame]301<p><strong>Note:</strong>&nbsp; When using this feature the first segment of your URI must specify the folder. For example, lets say you have a controller
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]302located here:</p>
303
304<code>application/controllers/<kbd>products</kbd>/shoes.php</code>
305
306<p>To call the above controller your URI will look something like this:</p>
307
Derek Allarde370a352008-05-03 14:14:36 +0000[diff] [blame]308<code>www.your-site.com/index.php/products/shoes/show/123</code>
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]309
admine3817a32006-09-05 03:30:46 +0000[diff] [blame]310<p>Each of your sub-folders may contain a default controller which will be
311called if the URL contains only the sub-folder. Simply name your default controller as specified in your
312<dfn>application/config/routes.php</dfn> file</p>
313
314
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]315<p>CodeIgniter also permits you to remap your URIs using its <a href="routing.html">URI Routing</a> feature.</p>
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]316
317
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]318<h2><a name="constructors"></a>Class Constructors</h2>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]319
320
321<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>
322
323<code>parent::Controller();</code>
324
325<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>
326
327
admin2c676ef2006-09-21 16:54:44 +0000[diff] [blame]328<p>If you are not familiar with constructors, in PHP 4, a <em>constructor</em> is simply a function that has the exact same name as the class:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]329
330<code>
331&lt;?php<br />
332class <kbd>Blog</kbd> extends Controller {<br />
333<br />
334&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;function <kbd>Blog()</kbd><br />
335&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
336&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<var>parent::Controller();</var><br />
337&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
338}<br />
339?&gt;</code>
340
341<p>In PHP 5, constructors use the following syntax:</p>
342
343<code>
344&lt;?php<br />
345class <kbd>Blog</kbd> extends Controller {<br />
346<br />
347&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;function <kbd>__construct()</kbd><br />
348&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
349&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<var>parent::Controller();</var><br />
350&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
351}<br />
352?&gt;</code>
353
354<p>Constructors are useful if you need to set some default values, or run a default process when your class is instantiated.
355Constructors can't return a value, but they can do some default work.</p>
356
357<a name="reserved"></a>
358<h2>Reserved Function Names</h2>
359
admine334c472006-10-21 19:44:22 +0000[diff] [blame]360<p>Since your controller classes will extend the main application controller you
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]361must be careful not to name your functions identically to the ones used by that class, otherwise your local functions
Derek Allardee0a7f02008-05-08 13:59:27 +0000[diff] [blame]362will override them. See <a href="reserved_names.html">Reserved Names</a> for a full list.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]363
364<h2>That's it!</h2>
365
366<p>That, in a nutshell, is all there is to know about controllers.</p>
367
368
369
370</div>
371<!-- END CONTENT -->
372
373
374<div id="footer">
375<p>
Derek Allardee0a7f02008-05-08 13:59:27 +0000[diff] [blame]376Previous Topic:&nbsp;&nbsp;<a href="reserved_names.html">Reserved Names</a>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]377&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
378<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
379<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Derek Allardee0a7f02008-05-08 13:59:27 +0000[diff] [blame]380Next Topic:&nbsp;&nbsp;<a href="views.html">Views</a></p>
Derek Jones07870432008-02-13 03:49:26 +0000[diff] [blame]381<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2008 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]382</div>
383
384</body>
385</html>