4. The Controller

Controllers are the workhorses behind your application. They are simply classes that perform the following function:

Carry out all logic
Generate and return a View instance

Class location

You must create a Controller class within either the [app.dir.controllers], [core.dir.controllers] or [ext.*.dir.controllers] folder, name it using the UpperCamelCaps convention and always suffix with the word Controller. For example:

[app.dir.controllers]/HomeController.php
[app.dir.controllers]/AccountRegisterController.php

[core.dir.controllers]/admin/AccountController.php
[core.dir.controllers]/api/public/PeopleController.php

Note that you can also store Controller classes within sub-folders which are named using the lower-hyphenated convention. If you decide to use sub-folders, then remember to create an IndexController.php within that folder to handle requests which don't explicitly specify a Controller.

Class structure

The basic structure of a Controller class is as follows:

<?php
/* Placed in, for example, [app.dir.controllers]/BlogController.php */

class BlogController extends Controller {

	protected $privateMethods = array('query');

	public function index($params) {
		$view = new View();
		$view->setSource('/path/to/a/template.tpl');
		return $view;
	}

	public function unknown($params, $requestedAction) {
		...
	}

	public function findPost($params) {
		...
	}

	public function query($params) {
		...
	}

	private function init() {
		...
	}
}
?>

In this example we have created the Blog Controller with five actions; index, unknown, findPost, query and init. You can actually create a Controller which contains no actions whatsoever, in which case the special index and unknown actions will be inherited from the Controller class (or your own custom Controller class if applicable).

Note that every method that corresponds to a controller-action must support at least a single argument ($params in our example) which basically holds every parameter passed via the URL, in the same order they appear in the URL.

The $privateMethods class property is entirely optional and is used to tell Buan which of the Controller's public methods must NOT be executed from the URL. In this example the query action is blocked from being called via the URL. You can achieve the same effect by simply defining your class method as private, as we've done for init in our example, but this facility gives you more flexibility if, for example, you wanted your class method to be executable from elsewhere in your application.

If this Controller were to be called from a URL that hasn't specified an action, then Buan would default to executing the index action.

If a non-existent action was called then the call would be passed through to the unknown action and the $requestedAction argument in our example would contain that originally requested action.

The class methods must use the lowerCamelCaps naming convention, but in the URL they will map to the equivalent lower-hyphenated string as described below.

All actions must return an instance of the View class (or your own custom class if applicable).

Mapping a URL to a controller/action

The default url-parsing process in UrlCommand::create() will peform the following basic mapping:

# Given URL: www.mydomain.com/blog/find-post/joe+bloggs?orderby=date
# Look in all controller folders for BlogController.php
# Execute the findPost() method and pass it the array of parameters, array('joe bloggs')
# Note that the orderby query parameter will be available as normal in $_GET['orderby']

You may also define your own parsing function/class-method to override this default behaviour. See How it works for more details.

Table of contents