ExpressionEngine Docs

# Controllers

- What is a Controller?
- Let’s try it
- Methods
- Passing URI Segments to your methods
- Remapping Method Calls
- Private methods

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

## What is a Controller?

A Controller is simply a class file that is named in a way that can be associated with a URI. ExpressionEngine uses Controllers for all of its Control Panel pages. An `mcp` file within a module is a controller as well and typically what you’ll be dealing with.

Consider this URI:

    example.com/system/index.php?/cp/addons/settings/my_addon

In the above example, ExpressionEngine would attempt to find a controller named `mcp.my_addon.php` within the `system/ee/user/addons/my_addon/` directory and load it.

## Let’s try it

First, ensure that your add-on has `settings_exist` set to true in its addon.setup.php file. Then create a simple module control panel so you can see it in action. Using your text editor, create a file called `mcp.my_addon.php`, and put the following code in it:

    <?php

    class My_addon_mcp {

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

Then save the file to your `system/ee/user/addons/my_addon/` directory.

Important: The file must be called `mcp.my_addon.php` and be placed in the `system/ee/user/addons/my_addon/` directory. You can change `my_addon` to whatever you want, but both the directory and file must match.

Now visit the Add-on Manager and click on the cog next to your add-on’s name. If you did it right, you should see:

> Hello World!

Important: Class names must start with an uppercase letter.

This is valid:

    class My_addon_mcp {

This is not valid:

    class my_addon_rte {

## Methods

In the above example the method name is `index()`. The “index” method is always loaded by default if there is no segment after your add-on’s name. Another way to show your “Hello World” message would be this:

    example.com/system/index.php?/cp/addons/settings/my_addon/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 My_addon_mcp {

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

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

Now load the following URL to see the comment method:

    example.com/system/index.php?/cp/addons/settings/my_addon/comments

You should see your new message.

## Passing URI Segments to your methods

You can pass additional URI segments to your methods when creating URLs like so:

    example.com/system/index.php?cp/addons/settings/my_addon/comments/asc/10

Then back in your controller:

    public function comments($direction = 'desc', $limit = '25')
    {
        ...

If you want to use this functionality for the `index()` method, be sure to specify `index` in your URLs:

    example.com/system/index.php?cp/addons/settings/my_addon/index/asc/10

## Remapping Method Calls

As noted above, the second segment of the URI typically determines which method in the controller gets called. ExpressionEngine 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')
        {
            return $this->$method();
        }
        else
        {
            returtn $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 ExpressionEngine’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();
    }

## 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/system/index.php?/cp/addons/settings/my_addon/utility