^Status|Draft|
^Todo|sub-folders, method parameters, remapping example, Proof read|


====== Controllers ======

Controllers stand in between the models and the views in an application. They pass information on to the model when data needs to be changed and they request information from the model. For example  database inserts, updates and deletes for data change and database selects for information retrieval. 
Controllers pass on the information of the model to the views, the views contain the final output for the users.

Controllers are called by a URL, see [[urls|Urls]] for more information.


===== Controller naming and anatomy =====

A controller's filename can be basically anything. The name of the controller class must correspond to the filename. 

**Conventions for a controller**
  * must reside in a ''controllers'' (sub-)directory 
  * controller filename must be lowercase, e.g. ''articles.php''
  * controller class must map to filename and capitalized, and must be appended with **_Controller**, e.g. **Articles_Controller**
  * must have the Controller class as (grand)parent
  * controller methods preceded by '_' (e.g. **_do_something**() ) cannot be called by the URI mapping


==== A simple controller ====
We start with a simple controller. It will show Hello World on the screen.

**application/controllers/article.php**
<code php>
<?php defined('SYSPATH') OR die('No direct access allowed.');

class Article_Controller extends Controller
{
    public function index()
    {
        echo 'Hello World!';
    }
}
</code>
Now if you enter yoursite.com/article (or yoursite.com/index.php/article without URL rewritting) you should see

<code>
Hello World
</code>

That's it, your first controller. You can see all conventions are applied.


==== More advanced controller ====
In the example above the ''index()'' method is called by the yoursite.com/article url. If the second segment of the url is empty, the index method is called. It would also be called by the following url: yoursite.com/article/index

__If the second segment of the url is not empty, it determines which method of the controller is called.__ 


**application/controllers/article.php**
<code php>
class Article_Controller extends Controller
{
    public function index()
    {
        echo 'Hello World!';
    }

    public function overview()
    {
        echo 'Article list goes here!';
    }
}
</code>
Now if you call the url yoursite.com/article/overview it will display 

<code>
Article list goes here!
</code>


==== Controller with arguments ====
Say we want to display a specific article, for example the article with the title being ''your-article-title'' and the id of the article is ''1''. 

The url would look like yoursite.com/article/view/**your-article-title**/**1** The last two segments of the url are passed on to the view() method. 

**application/controllers/article.php**
<code php>
class Article_Controller extends Controller
{
    public function index()
    {
        echo 'Hello World!';
    }

    public function overview()
    {
        echo 'Article list goes here!';
    }

    public function view($title,$id)
    {
        echo $id . ' - ' . $title;
        // you'd retrieve the article from the database here normally
    }
}
</code>
When you call yoursite.com/article/view/**your-article-title**/**1** it will display 

<code>
1 - your-article-title
</code>

===== Controllers and subdirectories =====
If you put a controller in a subdirectory of the /controllers/ directory, Kohana will include the subdirectory in the mapping to the controller. E.g. a file in ''application/controllers/admin/user.php'' will correspond to the url http://localhost/admin/user

===== Routing controllers elsewhere =====
If for some reason the mapping from the URI to the controller and method is not right for you you can use routing to map a URI to another controller.
E.g. have ''localhost/about/me'' map to http://localhost/articles/view/1 

See [[general:routing|Routing]] for more information on this.

===== Special methods =====

==== __construct ====

If you declare a constructor in your controller, for example to load some resources for the entire controller, you have to call the parent constructor.

**application/controllers/article.php**

<code php>
class Article_Controller extends Controller
{
    protected $db;
    protected $session;

    public function __construct()
    {
        parent::__construct(); // This must be included

        $this->db = Database::instance();
        $this->session = Session::instance();
    }

    public function index()
    {
        $this->session->get('user_id');
    }

    public function view($article_id)
    {
        $article = $this->db->getwhere('articles', array('id' => (int) $article_id));
    }
}
</code>

This example also shows how you can retrieve an article from the database using URL segments. If you call ''yoursite.com/article/view/5'', it will retrieve the article whose ''id'' is ''5''.

==== index ====

''index()'' is the method that will be called by default, when no method segment is provided in the URL.
E.g. if your controller is called ''Welcome_Controller'', and the URL is http://yoursite.com/welcome then the ''index'' method is called.

Note: You cannot pass arguments to an index method, unless the URI contains **index** in segment two. 

==== __call ====

''%%__call%%($method, $arguments)'' is the method called when a method of a controller is called that doesn't exist. It is declared in the Controller class and will trigger a 404 by default. You can override this method in your own controllers for advanced functionality.

 
**application/controllers/article.php**
<code php>
class Article_Controller extends Controller
{
    public function __call($method,$arguments)
    {
        $id=(int) $method;
        $this->view($id);
    }

    public function view($id)
    {
        echo $id;
        // you'd retrieve the article from the database here normally
    }
}
</code>
When you call yoursite.com/article/**1** , it will display the article. You see that the second segment now is the ''$id'' instead of the controller method.

==== Private methods ====
Sometimes you want some methods in your controller which should not be available on your website. They are only used internally. This can be done by declaring methods private and/or prepending them with **_**

**application/controllers/article.php**
<code php>
class Article_Controller extends Controller
{
    public function index()
    {
        echo 'Hello World!';
    }

    private function _article_form()
    {
        echo 'Article form';
    }
}
</code>
When you call yoursite.com/article/_article_form you'll encounter a 404.


===== Special Controllers =====

==== Using a base controller for your application ====
Using a base controller for your application can be very helpful. You can execute code on every page for example, useful for authenticating and authorizing users for example or doing session magic.

**Example** ''MY_Controller.php''
<code php>
<?php 

class Controller extends Controller_Core
{
    public function __construct()
    {
        parent::__construct();

        // authentication goes here for example
    }

    public function do_something()
    {
        // method available in all controllers
    }
}
</code>
The file should be named ''MY_Controller.php'' It should then be placed in ''application/libraries'' This class has all the methods of the original Controller plus your own. 

Note: The prefix **MY_** can be configured in ''application/config/config.php'' by changing the **$config['extension_prefix']**