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