Fuel Documentation

Controllers

What is a controller?

Controllers are classes that can be reached through the URL and take care of handling the request. A controller calls models and other classes to fetch the information and finally will pass everything to a view for output. If a URL like www.yoursite.com/example/index is requested, the first segment will be which controller is called ("example") and the second which method of that controller is called ("index").

Creating a controller

In Fuel Controllers are put in the fuel/app/classes/controller directory. They should (but don't have to) extend the Controller class and are prefixed by default by "Controller_". Below is an example of the controller "example":

class Controller_Example extends Controller {

	public function action_index()
	{
		$data['css'] = Asset::css(array('reset.css','960.css','main.css'));
		$this->output = View::factory('test/index', $data);
	}
}

Methods that can be requested through the URL are prefixed with "action_", this means that you're not limited by PHP's constructs on which name you might use (example: method "list" isn't allowed, "action_list" is no problem). But this also means you can give your controller public methods that can be used from other classes but are not routable.

Using more parameters from the URL

Let say we also have the following method in our Controller_Example:

public function action_name_to_upper($name, $name_2)
{
	$data['name'] = strtoupper($name);
	$data['name_2'] = strtoupper($name_2);
	$this->output = View::factory('test/name_to_upper', $data);
}

If we call this method using www.yoursite.com/example/name_to_upper/fuel/php it will return the view test/name_to_upper with it given "Fuel" and "PHP" as values $name_1 and $name_2.

Controller in a subdirectory

You can also put a controller in a subdirectory like fuel/app/classes/controller/dir/test.php in such a case the controller must include the dirname in the classname like this Controller_Dir_Test.

Please Note: Only 1 level of subdirectories is supported.

Special controller methods

action_index()

This method will be called if the controller is called without a second parameter. In the above example www.yoursite.com/example/index will be the same as www.yoursite.com/example.

before()

This method will be executed before the method from the URL is called on your controller, even if that method turns out not to exist.

after()

This method will be executed after the method from the URL was called successfully, this will not be called if the method turns out not to exist.

router($method, $params)

This method will take over the internal routing of the controller. Once the controller is loaded the router() method will be called and given the $method that would have been called without the router() method and the $params in an array that would have been given to that method. before() and after() will work as expected.

Special controller properties

$request

This property holds the Request object and may not be overwritten, it can be used though to get information about the current request.

$output

This property holds the output that will be given to the browser, if you want to output anything don't echo it just add it to the $this->output property.

Extending other controllers

Thanks to the autoloader you can extend other controllers without writing anything more than its name in the class definition:

class Controller_Example extends Controller_Welcome {

	// your methods

}

This may sound strange at first, but extending controllers allows you to share methods and create base controllers really easily.

Creating Base Controllers

A base controller is a shared controller, like Controller_Public or Controller_Admin and are used to share logic between groups of controllers. For example, the Controller_Admin controller could contain your login/logout actions and maybe a dashboard, but it could also contain a before() method that checks to see if the user is logged in as an admin. Then all other controllers in your admin panel will extend this an automatically be secured.

class Controller_Admin extends Controller {

	public function before()
	{
		// check for admin
	}

	// your methods

	public function action_index()
	{
		// load the dashboard
	}

	public function action_login()
	{
		// log in the user
	}
}

That code will go in fuel/app/classes/controller/admin.php and all of your other controllers should go in fuel/app/classes/controller/admin/users.php:

class Controller_Admin_User extends Controller_Admin {

	public function action_index()
	{
		// overrides the dashboard with the user index listing
	}

	public function action_edit($id)
	{
		// edit users
	}
}