Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 6ac4bea2da9e64fb0b434f52177353f6bd65b8e6 / . / user_guide / general / controllers.html
blob: 4dc94cba6212f0c56317ebcc83bef9ed15380189 [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;
50Controllers
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>Controllers</h1>
64
65<p>Controllers are the heart of your application, as they determine how HTTP requests should be handled.</p>
66
67
68<ul>
69<li><a href="#what">What is a Controller?</a></li>
70<li><a href="#hello">Hello World</a></li>
71<li><a href="#functions">Functions</a></li>
72<li><a href="#private">Private Functions</a></li>
73<li><a href="#default">Defining a Default Controller</a></li>
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]74<li><a href="#subfolders">Organizing Controllers into Sub-folders</a></li>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]75<li><a href="#constructors">Class Constructors</a></li>
76<li><a href="#reserved">Reserved Function Names</a></li>
77</ul>
78
79
80<a name="what"></a>
81<h2>What is a Controller?</h2>
82
83<p><dfn>A Controller is simply a class file that is named in a way that can be associated with a URI.</dfn></p>
84
85<p>Consider this URI:</p>
86
87<code>www.your-site.com/index.php/<var>blog</var>/</code>
88
89<p>In the above example, Code Igniter would attempt to find a controller named <dfn>blog.php</dfn> and load it.</p>
90
91<p><strong>When a controller's name matches the first segment of a URI, it will be loaded.</strong></p>
92
93<a name="hello"></a>
94<h2>Let's try it:&nbsp; Hello World!</h2>
95
96<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>
97
98
99<textarea class="textarea" style="width:100%" cols="50" rows="10">
100<?php
101class Blog extends Controller {
102
103 function index()
104 {
105 echo 'Hello World!';
106 }
107}
108?>
109</textarea>
110
111
112
113<p>Then save the file to your <dfn>application/controllers/</dfn> folder.</p>
114
115<p>Now visit the your site using a URL similar to this:</p>
116
117<code>www.your-site.com/index.php/<var>blog</var>/</code>
118
119<p>If you did it right, you should see <samp>Hello World!</samp>.</p>
120
121<p>Note: Class names must start with an uppercase letter. In other words, this is valid:
122
123<code>&lt;?php<br />
124class <var>Blog</var> extends Controller {<br />
125<br />
126}<br />
127?&gt;</code>
128
129<p>This is <strong>not</strong> valid:</p>
130
131<code>&lt;?php<br />
132class <var>blog</var> extends Controller {<br />
133<br />
134}<br />
135?&gt;</code>
136
137<p>Also, always make sure your controller <dfn>extends</dfn> the parent controller class so that it can inherit all its functions.</p>
138
139
140
141<a name="functions"></a>
142<h2>Functions</h2>
143
144<p>In the above example the function name is <dfn>index()</dfn>. The "index" function is always loaded by default if the
145<strong>second segment</strong> of the URI is empty. Another way to show your "Hello World" message would be this:</p>
146
147<code>www.your-site.com/index.php/<var>blog</var>/<samp>index</samp>/</code>
148
149<p><strong>The second segment of the URI determines which function in the controller gets called.</strong></p>
150
151<p>Let's try it. Add a new function to your controller:</p>
152
153
154<textarea class="textarea" style="width:100%" cols="50" rows="15">
155<?php
156class Blog extends Controller {
157
158 function index()
159 {
160 echo 'Hello World!';
161 }
162
163 function comments()
164 {
165 echo 'Look at this!';
166 }
167}
168?>
169</textarea>
170
171<p>Now load the following URL to see the <dfn>comment</dfn> function:</p>
172
173<code>www.your-site.com/index.php/<var>blog</var>/<samp>comments</samp>/</code>
174
175<p>You should see your new message.</p>
176
177<a name="private"></a>
178<h2>Private Functions</h2>
179
180<p>In some cases you may not want certain functions accessible publicly. To make a function private, simply add an
181underscore 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>
182
183<code>
184function _utility()<br />
185{<br />
186&nbsp;&nbsp;// some code<br />
187}</code>
188
189<p>Trying to access it via the URL, like this, will not work:</p>
190
191<code>www.your-site.com/index.php/<var>blog</var>/<samp>_utility</samp>/</code>
192
193
194
195<a name="default"></a>
196<h2>Defining a Default Controller</h2>
197
198<p>Code Igniter can be told to load a default controller when a URI is not present,
199as will be the case when only your site root URL is requested. To specify a default controller, open
200your <dfn>application/config/routes.php</dfn> file and set this variable:</p>
201
202<code>$route['default_controller'] = '<var>Blog</var>';</code>
203
204<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
205specifying any URI segments you'll see your Hello World message by default.</p>
206
207
adminb071bb52006-08-26 19:28:37 +0000[diff] [blame]208<a name="subfolders"></a>
209<h2>Organizing Your Controllers into Sub-folders</h2>
210
211<p>If you are building a large application you might find it convenient to organize your controllers into sub-folders. Code Igniter permits you to do this.</p>
212
213<p>Simply create folders within your <dfn>application/controllers</dfn> directory and place your controller classes within them.</p>
214
admin1082bdd2006-08-27 19:32:02 +0000[diff] [blame]215<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]216located here:</p>
217
218<code>application/controllers/<kbd>products</kbd>/shoes.php</code>
219
220<p>To call the above controller your URI will look something like this:</p>
221
222<code>www.your-site.com/index.php/products/shoes/123</code>
223
224<p>Code Igniter also permits you to remap your URIs using its <a href="routing.html">URI Routing</a> feature.
225
226
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]227<a name="constructors"></a>
228<h2>Class Constructors</h2>
229
230
231<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>
232
233<code>parent::Controller();</code>
234
235<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>
236
237
238<p>If you are not familliar with constructors, in PHP 4, a <em>constructor</em> is simply a function that has the exact same name as the class:</p>
239
240<code>
241&lt;?php<br />
242class <kbd>Blog</kbd> extends Controller {<br />
243<br />
244&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;function <kbd>Blog()</kbd><br />
245&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
246&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<var>parent::Controller();</var><br />
247&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
248}<br />
249?&gt;</code>
250
251<p>In PHP 5, constructors use the following syntax:</p>
252
253<code>
254&lt;?php<br />
255class <kbd>Blog</kbd> extends Controller {<br />
256<br />
257&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;function <kbd>__construct()</kbd><br />
258&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
259&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<var>parent::Controller();</var><br />
260&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
261}<br />
262?&gt;</code>
263
264<p>Constructors are useful if you need to set some default values, or run a default process when your class is instantiated.
265Constructors can't return a value, but they can do some default work.</p>
266
267<a name="reserved"></a>
268<h2>Reserved Function Names</h2>
269
270<p>Since your controller classes will extend the main application controller you
271must be careful not to name your functions identically to the ones used by that class, otherwise your local functions
272will override them. The following
273is a list of reserved names. Do not name your controller functions any of these:</p>
274
275<ul>
276<li>Controller</li>
277<li>CI_Base</li>
278<li>_ci_autoload</li>
279<li>_ci_autoloader</li>
280<li>_ci_assign_core</li>
281<li>_ci_initialize</li>
282<li>_ci_init_database</li>
283<li>_ci_init_scaffolding</li>
284<li>_ci_is_loaded</li>
285<li>_ci_load</li>
286<li>_ci_scaffolding</li>
287<li>_ci_set_view_path</li>
288</ul>
289
290<p><br />If you are running PHP 4 there are some additional reserved names. These ONLY apply if you are running PHP 4.</p>
291
292<ul>
293<li>CI_Loader</li>
294<li>config</li>
295<li>database</li>
296<li>file</li>
297<li>helper</li>
298<li>helpers</li>
299<li>language</li>
300<li>library</li>
301<li>plugin</li>
302<li>plugins</li>
303<li>scaffolding</li>
304<li>script</li>
305<li>view</li>
306<li>vars</li>
307</ul>
308
309
310
311
312
313
314<h2>That's it!</h2>
315
316<p>That, in a nutshell, is all there is to know about controllers.</p>
317
318
319
320</div>
321<!-- END CONTENT -->
322
323
324<div id="footer">
325<p>
326Previous Topic:&nbsp;&nbsp;<a href="urls.html">Code Igniter URLs</a>
327&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
328<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
329<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
330Next Topic:&nbsp;&nbsp;<a href="views.html">Views</a>
331<p>
332
333<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>
334</div>
335
336</body>
337</html>