Controller

Description

The 'Controller' module is "C" in the Model-View-Controller (MVC) architectural pattern.

It can be useful if you want to use MVC in Drupal like it can be done in MVC frameworks (like ZF, Yii and so on).

The 'controller' module allows to use a Page Controllers (Action Controllers) for your pages. The Controller is just class that has set of actions. Each action is a separate method that will be called for specified path (page).

For example if you have the 'foo/bar' path (URI), then you can create a new class called FooBarPageController and myAction method (you can use other names of course). This method will be called for the 'http://host/foo/bar' address.

Important note 1: it is utility module for programmers only.

Important note 2: the Controller object that acts as page handler is not the same as Controller that implements DrupalEntityControllerInterface - they are different things and used for different purposes.

Example

Here is a screencast that shows main features.

Let's say that you have the 'mymodule' module and you want to call the FooBarPageController::myAction() method for the 'foo/bar' path. To do that you can do the following:
1. Create new directory mymodule/controllers/.

2. Create new file called FooBarPageController.php inside this directory.

3. Add the following code into it:

/**
 * My test controller class.
 */
class MymoduleFooBarPageController {
  /**
   * This method that will be called for the 'foo/bar' path.
   *
   * @path => 'foo/bar',
   * @access arguments => array('access arguments'),
   * @title => 'My test page',
   */
  function myAction() {
    return sprintf('<pre>%s</pre>', __METHOD__ . ' called with args: '
      . print_r(func_get_args(), 1));
  }
}

4. Define the hook_controller_api() as follows:

/**
 * Implements hook_controller_api().
 */
function mymodule_controller_api() {
  return '2.x';
}

5. Go to the /admin/config/development/performance (Drupal 7) and click the "Clear all caches" button.

6. Now go to the 'foo/bar' page and you should see output from action method myAction().

Format of PHP annotations

The 'controller' module uses PHP annotations to define routes that were defined in the hook_menu() previously.

The format of annotations is very simple:

/**
 * key_1 => php_code_1;
 * key_2 => php_code_2,
 * ...
 * key_n => php_code_n;
 */

Each line can optionally end with ; or , (it may be useful if you have a habit to enter them inside your PHP code).

Allowed items are:

1. @title, @access arguments, @access callback, @title, @description, @page arguments etc., see hook_menu() for the full list of allowed keys.
2. @path - for each action method it is string, containing path (URI), that will be associated with the method.
3. @default - you can mark with @default the actions that will be considered as MENU_DEFAULT_LOCAL_TASKs. For example:
   

   * @path => 'my/path',
   * @title => 'My title',
   * @default => array('local/task' => 'My default local task title'),
   

   For this particular example the two menu items will be generated:
   - one with the 'my/path', the MENU_NORMAL_ITEM type and the 'My title' title.
   and
   - one with the 'my/path/local/task' path and MENU_DEFAULT_LOCAL_TASK type with the 'My default local task title'.

Note: all action methods that don't define the @type element by default will have the MENU_CALLBACK type.

Conventions for names

There are some conventions that should be used to allow the 'controller' module work properly.
1. The directory name should be 'controllers/'
2. The Controller's class name should be prefixed with the CamelCased version of the module name with capital first latter. For our example it is 'Mymodule' prefix. If the 'controller_use_ns' variable is on the prefix will be used as namespace, so the the full class name will be \Mymodule\FooBarPageController. You can change value of the 'controller_use_ns' variable on the '/admin/settings/controller' for Drupal 6 or 'admin/config/controller' for Drupal 7.

How it works?

The 'controller' module collects and parses PHP annotations (PHP doc blocks) and rewrites them to so that the controller_menu_handler() will be called for all paths. As first argument this function always takes the meta information that describes actual callback that should be called. By using this meta information the controller_menu_handler() will call this callback with list of arguments that were described in the PHP annotations.

What additions give the 'controller' module?

1. Each Controller is class, so you the OOP (Object Oriented Programming) approach can applied. For example you can define new base Controller class and extend it in your Controllers.
2. The hook_menu() may not be defined at all - all mapping can be defined in your Controllers.
3. Your menu/path handlers can be placed within one controllers/ directory and grouped with using of classes. So you can more easily find your menu handler by looking on name of class/file.