Documentation / Controllers

Controllers are the gears behind modules' URI access. They contains the code that will interact with models and views.

For now, Orion has three built-in controller types : the base controller (Orion\Core\Controller) and two sub-controllers that inherit from it : the template controller (Orion\Core\Controller\Template) and the restful controller (Orion\Core\Controller\Restful)

Note that you can easily create your own controller type, by creating a new class in the Orion\Core\Controller namespace that will extend the base controller.

Base controller

Orion\Core\Controller (orion/core/controller.php)

This is the basic controller to extend when creating a module's controller. It provides support for the following minimal features :

  • Auth (User restriction)
  • Route
  • Response

Auth

This feature is accessible using the allow($rank) method and enables you to restrict access to a part, or all, of a module's controller to a certain user rank.

Note that this method is only usable if you have configured user access in Orion's configuration file and created the corresponding tables in your database.

With this method, you can either restrict access to the entire module's controller by calling it inside its constructor or restrict only a method by calling it inside that very method :

class MymoduleDefault extends Core\Controller
{
   public function __construct()
   {
       $this->allow('member');
       // This will deny any visitor or user with a rank lower than 'member' access to this module's controller
   }

   public function _someMethod()
   {
       $this->allow('administrator');
       // This will deny any visitor or user with a rank lower than 'administrator' access to this method. This has no influence on other methods.
   }
}

Route

This feature is accessible using the Core\Route class and the route attribute of the controller. It enables the creation of custom routing rules.

To define custom rules, you have assign a new Core\Route object to the route attribute of the controller and then add your custom rules.

public function __construct()
{
    $this->route = new Core\Route();
    // Mapping the 'do' URI the the _process($type, $id) method
    $this->route->addRule('do/?/@', 'process');
    // Mapping the default URI to the _showform() method
    $this->route->setDefaultMethod('showform');
}

This will redirects any mymodule/do/something/1234.html calls to the _process($type, $id) method with arguments $type = 'something' and $id = 1234.

This will also map the default mymodule.html call to the _showform() method.

If no routing object is provided, the controller will try to map URI calls to methods automatically (although this is not recommend).

More information about routing can be found in the Routing doc.

Response

This feature is a simple response method that outputs contents before exiting the script.

It is accessible via the respond($output, $exit, $headerCode) method.

For example :

public function _someRestrictedControllerMethod()
{
    $this->respond('You don\'t have the permissions to access this file.', true, 401);
}

This method will :

  • Write a 401 Header using the Core\Context::setHeaderCode() method.
  • Echo 'You don\'t have the permissions to access this file.'
  • Exit the script with exit()

Using this function you can output almost anything from simple string to complete HTML code or raw data (ie. images).

Template controller

Orion\Core\Controller\Template (orion/core/controller/template.php)

Template controllers inherit all of the base controller's methods and add the following template-oriented features :

  • Renderer set/init
  • Template variable assignment
  • Template cache control
  • Asset include
  • View rendering

Renderer

You can define which renderer will be used to display your templates. Renderers are located in the orion/renderers/ directory.

This step is optional since it will load the default renderer provided in Orion's configuration file if no renderer is provided.

To use a different rendering engine, simply overwrite the renderer attribute of you controller :

class MymoduleDefault extends Core\Controller\Template
{
    protected $renderer = Core\Renderer::SMARTY;
}

Note that you can always access the rendering engine's instance class from your controller methods using the $tpl attribute of the template controller.

Template variable assignment

Use the assign($var, $content, $caching) method to store a template variable. For example :

public function _someMethod()
{
    $this->assign('myvariable', 'Some content here');
    $this->assign('arvariable', array('a'=>123, 'b'=> 456));
}

Note that some rendering engines support mixed variable content (like Smarty) while some others may not.

Template cache control

If supported by the current rendering engine, the template controller provides some methods to control caching. Like clearCache() or isCached().

Note that these methods are only shortcuts and thus, must be defined in your renderer's class. This also means that these methods may be directly callable through the tpl attribute of the template controller. For example, you can access a method x of the current rendering class by using :

$this->tpl->x();

Asset include

If supported by the rendering engine, the template controller provides another shortcut method to include a CSS stylesheet located in your module directory. For example, you can load a CSS file located in orion/modules/yourmodule/assets/style.css by calling :

$this->includeCSS('assets/style.css');

View rendering

If supported by the rendering engine, the template controller provides support for view file rendering. These views can inherit from a master template file.

Let's take an example. You're using the Smarty rendering engine, and have a default master template (a.k.a. theme) set inside your Orion configuration file. You can render a view located in view/info.tpl that will extend this theme by calling :

$this->renderView('views/info.tpl');

Note that the renderView($view, $cacheID, $compileID) supports cache and compile ID usage if the renderer itself supports it.

Also note that it is possible to set a custom theme for a template controller by using the setTemplate() method. This method is usable anywhere inside the module controller.

More information can be found inside the Renderer documentation.

RESTful controller

Orion\Core\Controller\Restful (orion/core/controller/restful.php)

Restful controllers inherit all of the base controller's methods and add the following REST-oriented features :

  • Request method testing
  • JSON response
  • Get PUT data

Request method testing

The RESTful controller provides a shortcut method to test the way the resource is accessed (PUT | POST | GET | DELETE).

Example :

public function _someMethod()
{
    if($this->isMethod('DELETE'))
    {
        // Delete resource
    }
}

JSON response

Another shortcut method of the restful controller is the send($mixed, $exit, $headerCode) method.

This method is simply an alias of the respond() method of the base controller, except that it encodes the $data provided into JSON using json_encode().

For example :

public function _someMethod()
{
    if($this->isMethod('GET'))
    {
        // Get resource
        $rsc = new Core\Object();
        $rsc->id = 1;
        $rsc->content = 'Hello';
        // Send the resource
        $this->send($rsc);
    }
}

Will output :

{
    "id" : 1,
    "content" : "Hello"
}

With a header status 200 OK.

Get PUT data

Since PHP does not permit to retrieve PUT data like it does for $_POST and $_GET, this methods allows you to get those data as an associative array. Simply call :

public function _someMethod()
{
    if($this->isMethod('PUT'))
    {
        $arr = $this->getPutData()
        // Handle $arr
    }
}
© Orion, the PHP5 framework, 2011-2012 • Maintained by Thibaut Despoulain
Back to top