user_guide/general/controllers.html

   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.0.2</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> &nbsp;&#8250;&nbsp;
  44 <a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
  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&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>
  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:&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 &lt;?php
  99 class Blog extends CI_Controller {
 100
 101         public function index()
 102         {
 103                 echo 'Hello World!';
 104         }
 105 }
 106 ?&gt;
 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>&lt;?php<br />
 122 class <var>Blog</var> extends CI_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 />
 130 class <var>blog</var> extends CI_Controller {<br />
 131 <br />
 132 }<br />
 133 ?&gt;</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 &lt;?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 ?&gt;
 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 &lt;?php<br />
 188 class Products extends CI_Controller {<br />
 189 <br />
 190 &nbsp;&nbsp;&nbsp;&nbsp;public 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
 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 &nbsp;&nbsp;&nbsp;&nbsp;// Some code here...<br />
 226 }</code>
 227
 228 <p class="important"><strong>Important:</strong>&nbsp; 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 &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 <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 &nbsp;&nbsp;&nbsp;&nbsp;$method = 'process_'.$method;<br />
 251 &nbsp;&nbsp;&nbsp;&nbsp;if (method_exists($this, $method))<br />
 252 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
 253 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return call_user_func_array(array($this, $method), $params);<br />
 254 &nbsp;&nbsp;&nbsp;&nbsp;}<br />
 255 &nbsp;&nbsp;&nbsp;&nbsp;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>&nbsp; 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 &nbsp;&nbsp;&nbsp;&nbsp;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-&gt;output-&gt;cache_expiration &gt; 0)<br />
 285 {<br />
 286 &nbsp;&nbsp;&nbsp;&nbsp;$this-&gt;output-&gt;_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 &nbsp;&nbsp;// 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>&nbsp; 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 &lt;?php<br />
 347 class <kbd>Blog</kbd> extends CI_Controller {<br />
 348 <br />
 349 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public function <kbd>__construct()</kbd><br />
 350 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
 351 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<var>parent::__construct();</var><br />
 352 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Your own constructor code<br />
 353 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
 354 }<br />
 355 ?&gt;</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:&nbsp;&nbsp;<a href="urls.html">CodeIgniter URLs</a>
 380 &nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 381 <a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 382 <a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 383 Next Topic:&nbsp;&nbsp;<a href="reserved_names.html">Reserved Names</a></p>
 384 <p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
 385 </div>
 386
 387 </body>
 388 </html>