Docs For Class Controller

Controller_Base

Description

Controller_Base is an abstract base class for implementing controllers.

Controllers are expected to provide one or more public methods which require no arguments to be passed. All such public methods are considered actions of the controller (unless the method name has been passed to hide_action()). Actions are automatically invoked to service a request depending on the request URL and the configured routing in the application.

For example, with default routing in place, a request to the URL "/hello" would invoke the index method of this controller:

class HelloController extends Controller_Base {
public function index() {
}
}

Unless the action explicitly renders a response, the render_action() method is called automatically when the method returns. By default, this would expect a view template to exist at "views/hello/index.tpl". That might look something like:

<html>
<head><title>Hello!</title></head>
<body>
Hello!
</body>
</html>

Variables may be passed to views through the use of instance variables. All public instances variables of your controller become variables of the same name in the view. So if we did this in our controller:

class HelloController extends Controller_Base {
public function index() {
$this->name = 'George';
}
}

The view file could then make use of the variable, like so:

<html>
<head><title>Hello!</title></head>
<body>
Hello, <?php echo htmlspecialchars($name); ?>!
</body>
</html>

Note that undeclared instance variables will be treated as public variables. You can prevent instance variables from being available to the view by specifically declaring them either protected or private:

class HelloController extends Controller_Base {
private $start_time;
public function index() {
$this->start_time = date('Y-m-d H:i:s');
$this->name = 'George';
}
}

So that in the view this would not output any date or time information in the second paragraph:

<html>
<head><title>Hello!</title></head>
<body>
Hello, <?php echo htmlspecialchars($name); ?>!
Request started at: <?php echo $start_time; ?>
</body>
</html>

abstract:

Located in /controller/lib/Controller/Base.php (line 131)

Variable Summary

mixed $action

mixed $event_listeners

mixed $flash

mixed $hidden_actions

mixed $layout

mixed $logger

mixed $rendered

mixed $_action_method

mixed $_cache_actions

mixed $_cache_headers

mixed $_is_error

mixed $_routing

mixed $_runtime_variables

mixed $_will_cache_action

Method Summary

Controller_Base __construct ()

string action ()

void add_event_listener (string $eventName, callback $function, [array $options = null])

void after_filter (string $name, [array $options = null])

boolean allowed_action (string $actionName)

void assign_template_vars (object $tpl)

void before_filter (string $name, [array $options = null])

void caches_action ()

void cache_options ()

string controller_name ()

void deliver_mail (string $recipients, string $subject, [array $options = array()])

void expire_action ([ $options = null])

void expire_fragment ([ $options = null])

bool fire_event (string $eventName, [bool $vetoable = false])

mixed flash (string $key)

string form_authenticity_token ()

void handle_request ()

boolean headers_for_cache ()

array hidden_actions ()

void hide_action ()

string layout ()

void logger ()

object model (string $className)

void not_found ()

void on_exception ( $exception, Exception $e)

void perform_action ()

array prepare_for_render (array $options)

boolean protect_from_forgery ()

void redirect_to (mixed $url)

bool remove_event_listener (string $eventName, callback $function)

bool rendered ()

void render_action ([array $options = array()])

void render_error (int $error_code, [array $options = array()])

void render_to_string ([array $options = array()])

void require_https ()

void require_post ()

void set_action (string $action)

void set_error (boolean $flag)

void set_flash (string $key, string $msg)

void set_layout (string $layout)

void set_rendered (bool $rendered)

void set_routing (Controller_Routing $routing)

void set_template_defaults ($template $template)

string template_cache_id ()

string template_compile_id ()

string url_for (array $parameters, [string $method = 'get'])

boolean will_cache (string $action)

mixed __get (string $name)

boolean __isset (string $name)

void __set (string $name, mixed $value)

void __unset (string $name)

Variables

mixed $action = NULL (line 135)

access: protected

mixed $event_listeners = array() (line 134)

access: protected

mixed $flash = NULL (line 136)

access: protected

mixed $hidden_actions = array('__construct'=>1,
'action'=>1,
'controller_name'=>1,
'flash'=>1,
'handle_request'=>1,
'layout'=>1,
'rendered'=>1,
'form_authenticity_token'=>1,
'expire_action',
'expire_fragment') (line 146)

access: protected

mixed $layout = NULL (line 133)

access: protected

mixed $logger = NULL (line 138)

access: protected

mixed $rendered = false (line 137)

access: protected

mixed $_action_method = null (line 144)

access: protected

mixed $_cache_actions = array() (line 142)

access: protected

mixed $_cache_headers = array('content-type'=>1,
'content-disposition'=>1,
'content-length'=>1,
'content-encoding') (line 157)

access: protected

mixed $_is_error = false (line 141)

access: protected

mixed $_routing = null (line 139)

access: protected

mixed $_runtime_variables = array() (line 140)

access: protected

mixed $_will_cache_action = false (line 143)

access: protected

Methods

Constructor __construct (line 165)

Constructor

access: public

Controller_Base __construct ()

action (line 173)

Accessor for this controller's action name

access: public

string action ()

add_event_listener (line 936)

Add an event listener to this class.

Options for the listener are:

only: Only invoke the listener for the specified actions (string or array of action names)
except: Invoke the listener for all actions except the specified ones (string or array of action names)

access: protected

void add_event_listener (string $eventName, callback $function, [array $options = null])

string $eventName: Name of the event to bind the listener to
callback $function: A callback function or method (will receive no arguments)
array $options: The list of options for the callback

after_filter (line 855)

Options for the filter are:

only: Only apply the filter for the specified actions (string or array of action names)
except: Apply the filter for all actions except the specified ones (string or array of action names)

access: protected

void after_filter (string $name, [array $options = null])

string $name: The name of the method to register.
array $options: The list of options for the filter

allowed_action (line 601)

Determine if an method can allowably be invoked as an action

access: protected

boolean allowed_action (string $actionName)

string $actionName: The action to test

assign_template_vars (line 769)

Assigns all public properties of the class as local variables in the template

access: protected

void assign_template_vars (object $tpl)

object $tpl: The template to assign variables on

before_filter (line 840)

Register a method on this class to be called before any request is processed. If the method that is called returns false, all processing of the request is stopped.

Options for the filter are:

only: Only apply the filter for the specified actions (string or array of action names)
except: Apply the filter for all actions except the specified ones (string or array of action names)

access: protected

void before_filter (string $name, [array $options = null])

string $name: The name of the method to register.
array $options: The list of options for the filter

caches_action (line 511)

Enable caching for one or more actions on this controller. Accepts one or more action names as parameters or an array of action names.

Actions may be conditionally cached by passing a list of options as the last argument to caches_action and specifying a callback with the 'if' option.

For example:

$this->caches_action('index', 'show', array('if'=>'not_logged_in'));

The above would then cause the controller to call the method not_logged_in to determine if the index and show actions would be cached.

access: protected

void caches_action ()

cache_options (line 915)

Return the cache options to use when caching an action

access: protected

void cache_options ()

controller_name (line 240)

Returns the name of the controller. For ExampleController this returns 'example'.

access: public

string controller_name ()

deliver_mail (line 700)

Deliver a multipart/alternative email

Additional options:

headers: Associative array of headers
attachments: An array of Support_Mail_Attachment objects

see: Controller_Base::render_action()
access: protected

void deliver_mail (string $recipients, string $subject, [array $options = array()])

string $recipients: A single recipient or an array of recipients
string $subject: Email subject
array $options: Any rendering options

expire_action (line 303)

Expire a cached action. Defaults to the current action.

For example:

$this->expire_action(array('action'=>'index'));

Would expire any cached content for the index action.

access: public

void expire_action ([ $options = null])

$options

expire_fragment (line 331)

Expire a cached fragment. Defaults to the current action and a null fragment name.

For example:

$this->expire_fragment(array('action'=>'index', 'fragment'=>'total_entries'));

Would expire a block in the index view that looked like:

{cache name="total_entries"}
Total entries: {$entries->count()}
{/cache}

access: public

void expire_fragment ([ $options = null])

$options

fire_event (line 990)

Notifies any registered event listeners

return: For vetoable events returns true if all listeners succeeded, false otherwise
access: protected

bool fire_event (string $eventName, [bool $vetoable = false])

string $eventName: The event name to notify listeners for
bool $vetoable: If true, any callback returning false ends the event chain

flash (line 279)

Return a flash message

return: The message or false
access: public

mixed flash (string $key)

string $key: The key of the message

form_authenticity_token (line 393)

Returns the current authenticity token to use in forms in conjunction with the protect_from_forgery() filter.

access: public

string form_authenticity_token ()

handle_request (line 400)

Process an incoming HTTP request

access: public

void handle_request ()

headers_for_cache (line 553)

Returns the list of headers which have been output that should be cached (or an empty list if none).

access: protected

boolean headers_for_cache ()

hidden_actions (line 590)

Return a list of all public methods which have been protected from use as an action.

access: protected

array hidden_actions ()

hide_action (line 571)

Accepts the names of one or more public methods which are protected from invocation as an action.

access: protected

void hide_action ()

layout (line 191)

Accessor for this controller's layout name

access: public

string layout ()

logger (line 1012)

Return a logger instance for the class

access: protected

void logger ()

model (line 1065)

A convenience method that calls Support_Util::model()

This method exists purely for more concise code creation. All three of the examples below perform the same operation:

// write this:
$post = $this->model('BlogPost')->find($id);
// instead of:
$post = Support_Util::model('BlogPost')->find($id);
// or
$BlogPost = new BlogPost();
$post = $BlogPost->find($id);

access: protected

object model (string $className)

string $className: The name of the model class to return

not_found (line 489)

Return a 404 not found message back.

access: protected

void not_found ()

on_exception (line 1025)

Handle an exception thrown in an action.

access: protected

void on_exception ( $exception, Exception $e)

Exception $e
$exception

perform_action (line 455)

Perform the current action. This method is intended only for use by handle_request().

access: public

void perform_action ()

prepare_for_render (line 737)

Prepare template and layout for rendering.

return: Array of array($prepared_template, $layout_name)
see: Controller_Base::render_action()
access: protected

array prepare_for_render (array $options)

array $options: Any additional rendering options

protect_from_forgery (line 901)

If the request is not a GET request and does not contain the

expected token, outputs a 403 Forbidden error and returns false, otherwise returns true. This is intended to be uses as a before filter to help in the prevention of cross-site request forgery attacks.

access: protected

boolean protect_from_forgery ()

redirect_to (line 614)

Output a redirect header to the browser

The $url parameter may be specified as a string, or passed as an array. If an array it provided, it is passed to the url_for() method to produce a URL for the redirect.

access: protected

void redirect_to (mixed $url)

mixed $url: URL or fragment to redirect to

remove_event_listener (line 962)

Remove an event listener from this class.

return: Returns true if the listener was found and removed
access: protected

bool remove_event_listener (string $eventName, callback $function)

string $eventName: Name of the event the listener is bound to
callback $function: The callback currently bound

rendered (line 212)

Accessor for this controller's rendered flag

access: public

bool rendered ()

render_action (line 631)

Render the template for the action

Options are:

action: Override the current action template to use
layout: The layout to use, or false for none

access: protected

void render_action ([array $options = array()])

array $options: Any rendering options

render_error (line 660)

Render an error document

Options are:

message: The HTTP status message to return
description: A more detailed description of the error (rarely used outside of logging)

access: protected

void render_error (int $error_code, [array $options = array()])

int $error_code: The HTTP error code (e.g. 404)
array $options: Any additional options

render_to_string (line 644)

Render the template as a string.

see: Controller_Base::render_action()
access: protected

void render_to_string ([array $options = array()])

array $options: Any rendering options

require_https (line 865)

If HTTPS is not the current protocol, outputs a redirect header to this URL using HTTPS and returns false, otherwise returns true. Convenient for use as a before filter on pages requiring HTTPS.

access: protected

void require_https ()

require_post (line 882)

If the current request method is not POST, outputs a 405 Method Not Allowed error and returns false, otherwise returns true. This is convenient for use in a conditional before filter to limit some actions to post only.

access: protected

void require_post ()

set_action (line 182)

This method sets the controller's action

access: public

void set_action (string $action)

string $action: The new action value

set_error (line 252)

Set the error flag for the controller

access: public

void set_error (boolean $flag)

boolean $flag: The flag value

set_flash (line 262)

Set a flash message

access: public

void set_flash (string $key, string $msg)

string $key: The key for the message
string $msg: The message to store

set_layout (line 203)

This method sets the path to the layout to be used.

A value of 'application' will expect a corresponding file named 'views/layouts/application.tpl'.

access: public

void set_layout (string $layout)

string $layout: The new layout to use

set_rendered (line 221)

This method sets the controller's rendered flag

access: public

void set_rendered (bool $rendered)

bool $rendered: The new rendered value

set_routing (line 230)

Set the routing instance currently in use

access: public

void set_routing (Controller_Routing $routing)

Controller_Routing $routing: The routing instance to set

set_template_defaults (line 792)

Set various template variables if they have not been set explicitly.

access: protected

void set_template_defaults ($template $template)

$template $template: The template object

template_cache_id (line 814)

Returns the current template cache ID, in case you want to vary the cached output based on some condition.

access: protected

string template_cache_id ()

template_compile_id (line 824)

Returns the current template compile ID, in case this controller changes the template directory.

access: protected

string template_compile_id ()

url_for (line 364)

Return the URL for a given set of parameters.

For example:

$this->url_for(array('controller'=>'session', 'action'=>'login'));

Will return "/session/login" if you have configured a route like:

$route->match('/:controller/:action');

If a URL cannot be determined, an exception is thrown.

access: public

string url_for (array $parameters, [string $method = 'get'])

array $parameters: The parameters to build the URL for
string $method: The HTTP method to produce the route for (default is "GET")

will_cache (line 536)

Returns true if the given action name will be cached

access: protected

boolean will_cache (string $action)

string $action: The name of the action to test

__get (line 1088)

Invoked when an attempt is made to retrieve the value of an undeclared instance variable

access: public

mixed __get (string $name)

string $name: The name of the variable

__isset (line 1100)

Invoked when an attempt is made to call isset or empty for an undeclared instance variable

access: public

boolean __isset (string $name)

string $name: The name of the variable

__set (line 1076)

Invoked when an attempt is made to set an undeclared instance variable

access: public

void __set (string $name, mixed $value)

string $name: The name of the variable
mixed $value: The value to set

__unset (line 1110)

Invoked when an attempt is made to unset an undeclared instance variable

access: public

void __unset (string $name)

string $name: The name of the variable

Documentation generated on Wed, 25 Apr 2012 09:46:40 -0700 by phpDocumentor 1.4.3