Controllers
***********

Controllers are the heart of your application, as they determine how
HTTP requests should be handled.


Page Contents
^^^^^^^^^^^^^

* Controllers

  * What is a Controller?

  * Let’s try it: Hello World!

  * Methods

  * Passing URI Segments to your methods

  * Defining a Default Controller

  * Remapping Method Calls

  * Processing Output

  * Private methods

  * Organizing Your Controllers into Sub-directories

  * Class Constructors

  * Reserved method names

  * That’s it!


What is a Controller?
=====================

**A Controller is simply a class file that is named in a way that can
be associated with a URI.**

Consider this URI:

   example.com/index.php/blog/

In the above example, CodeIgniter would attempt to find a controller
named Blog.php and load it.

**When a controller’s name matches the first segment of a URI, it will
be loaded.**


Let’s try it: Hello World!
==========================

Let’s create a simple controller so you can see it in action. Using
your text editor, create a file called Blog.php, and put the following
code in it:

   <?php
   class Blog extends CI_Controller {

           public function index()
           {
                   echo 'Hello World!';
           }
   }

Then save the file to your *application/controllers/* directory.

Important:

  The file must be called ‘Blog.php’, with a capital ‘B’.

Now visit the your site using a URL similar to this:

   example.com/index.php/blog/

If you did it right, you should see:

   Hello World!

Important:

  Class names must start with an uppercase letter.

This is valid:

   <?php
   class Blog extends CI_Controller {

   }

This is **not** valid:

   <?php
   class blog extends CI_Controller {

   }

Also, always make sure your controller extends the parent controller
class so that it can inherit all its methods.


Methods
=======

In the above example the method name is "index()". The “index” method
is always loaded by default if the **second segment** of the URI is
empty. Another way to show your “Hello World” message would be this:

   example.com/index.php/blog/index/

**The second segment of the URI determines which method in the
controller gets called.**

Let’s try it. Add a new method to your controller:

   <?php
   class Blog extends CI_Controller {

           public function index()
           {
                   echo 'Hello World!';
           }

           public function comments()
           {
                   echo 'Look at this!';
           }
   }

Now load the following URL to see the comment method:

   example.com/index.php/blog/comments/

You should see your new message.


Passing URI Segments to your methods
====================================

If your URI contains more than two segments they will be passed to
your method as parameters.

For example, let’s say you have a URI like this:

   example.com/index.php/products/shoes/sandals/123

Your method will be passed URI segments 3 and 4 (“sandals” and “123”):

   <?php
   class Products extends CI_Controller {

           public function shoes($sandals, $id)
           {
                   echo $sandals;
                   echo $id;
           }
   }

Important:

  If you are using the URI Routing feature, the segments passed to
  your method will be the re-routed ones.


Defining a Default Controller
=============================

CodeIgniter can be told to load a default controller when a URI is not
present, as will be the case when only your site root URL is
requested. To specify a default controller, open your
**application/config/routes.php** file and set this variable:

   $route['default_controller'] = 'blog';

Where ‘blog’ is the name of the controller class you want used. If you
now load your main index.php file without specifying any URI segments
you’ll see your “Hello World” message by default.

For more information, please refer to the “Reserved Routes” section of
the URI Routing documentation.


Remapping Method Calls
======================

As noted above, the second segment of the URI typically determines
which method in the controller gets called. CodeIgniter permits you to
override this behavior through the use of the "_remap()" method:

   public function _remap()
   {
           // Some code here...
   }

Important:

  If your controller contains a method named _remap(), it will
  **always** get called regardless of what your URI contains. It
  overrides the normal behavior in which the URI determines which
  method is called, allowing you to define your own method routing
  rules.

The overridden method call (typically the second segment of the URI)
will be passed as a parameter to the "_remap()" method:

   public function _remap($method)
   {
           if ($method === 'some_method')
           {
                   $this->$method();
           }
           else
           {
                   $this->default_method();
           }
   }

Any extra segments after the method name are passed into "_remap()" as
an optional second parameter. This array can be used in combination
with PHP’s call_user_func_array() to emulate CodeIgniter’s default
behavior.

Example:

   public function _remap($method, $params = array())
   {
           $method = 'process_'.$method;
           if (method_exists($this, $method))
           {
                   return call_user_func_array(array($this, $method), $params);
           }
           show_404();
   }


Processing Output
=================

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 Views and Output Class pages. In some cases,
however, you might want to post-process the finalized data in some way
and send it to the browser yourself. CodeIgniter permits you to add a
method named "_output()" to your controller that will receive the
finalized output data.

Important:

  If your controller contains a method named "_output()", it will
  **always** be called by the output class instead of echoing the
  finalized data directly. The first parameter of the method will
  contain the finalized output.

Here is an example:

   public function _output($output)
   {
           echo $output;
   }

Note:

  Please note that your "_output()" method will receive the data in
  its finalized state. Benchmark and memory usage data will be
  rendered, cache files written (if you have caching enabled), and
  headers will be sent (if you use that feature) before it is handed
  off to the "_output()" method. To have your controller’s output
  cached properly, its "_output()" method can use:

     if ($this->output->cache_expiration > 0)
     {
             $this->output->_write_cache($output);
     }

  If you are using this feature the page execution timer and memory
  usage stats might not be perfectly accurate since they will not take
  into account any further processing you do. For an alternate way to
  control output *before* any of the final processing is done, please
  see the available methods in the Output Library.


Private methods
===============

In some cases you may want certain methods hidden from public access.
In order to achieve this, simply declare the method as being private
or protected and it will not be served via a URL request. For example,
if you were to have a method like this:

   private function _utility()
   {
           // some code
   }

Trying to access it via the URL, like this, will not work:

   example.com/index.php/blog/_utility/

Note:

  Prefixing method names with an underscore will also prevent them
  from being called. This is a legacy feature that is left for
  backwards-compatibility.


Organizing Your Controllers into Sub-directories
================================================

If you are building a large application you might want to
hierarchically organize or structure your controllers into sub-
directories. CodeIgniter permits you to do this.

Simply create sub-directories under the main
*application/controllers/* one and place your controller classes
within them.

Note:

  When using this feature the first segment of your URI must specify
  the folder. For example, let’s say you have a controller located
  here:

     application/controllers/products/Shoes.php

  To call the above controller your URI will look something like this:

     example.com/index.php/products/shoes/show/123

Each of your sub-directories may contain a default controller which
will be called if the URL contains *only* the sub-directory. Simply
put a controller in there that matches the name of your
‘default_controller’ as specified in your
*application/config/routes.php* file.

CodeIgniter also permits you to remap your URIs using its URI Routing
feature.


Class Constructors
==================

If you intend to use a constructor in any of your Controllers, you
**MUST** place the following line of code in it:

   parent::__construct();

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.

Example:

   <?php
   class Blog extends CI_Controller {

           public function __construct()
           {
                   parent::__construct();
                   // Your own constructor code
           }
   }

Constructors are useful if you need to set some default values, or run
a default process when your class is instantiated. Constructors can’t
return a value, but they can do some default work.


Reserved method names
=====================

Since your controller classes will extend the main application
controller you must be careful not to name your methods identically to
the ones used by that class, otherwise your local functions will
override them. See Reserved Names for a full list.

Important:

  You should also never have a method named identically to its class
  name. If you do, and there is no "__construct()" method in the same
  class, then your e.g. "Index::index()" method will be executed as a
  class constructor! This is a PHP4 backwards-compatibility feature.


That’s it!
==========

That, in a nutshell, is all there is to know about controllers.
