This is documentation for Kohana v2.3.x. For v3.x documentation, see .

Table of Contents
TodoProof read

Event Class

For a programming overview of events, please see Event_handler and Event_loop. Kohana stores events in queues, as opposed to stacks. This simply means that, by default, new events will be processed after existing events.

What is an Event?

Kohana events consist of a unique name and a callback. By default, there are several events defined by Kohana. Names are completely freeform, but the convention is to use a to make event names more unique. All pre-defined events are prefixed as, eg: system.post_controller.


All Event methods are static, and Event should never be instanced.


Used to add a new callback to an event. If the event does not already exist, it will be created.

// Calls the function "foo" after the controller method is executed
Event::add('system.post_controller', 'foo');
// Calls the static method "Foo::bar" after the controller method is executed
Event::add('system.post_controller', array('foo', 'bar'));
// Calls the "bar" method in the "$foo" object when the output is rendered
Event::add('system.display', array($foo, 'bar'));

You can also create entirely new events this way:

// Creates a custom user.login event
Event::add('user.login', array($user, 'login'));


Used to add a callback immediately before another callback in an event.

// Add the function "faa" to be executed before "foo"
Event::add_before('system.post_controller', 'foo', 'faa');

If the event you are inserting before does not exist, add_before will function exactly the same as add.


Used to add a callback immediately after another callback in an event.

// Add the function "fzz" to be after "foo"
Event::add_after('system.post_controller', 'foo', 'fzz');

If the event you are inserting after does not exist, add_after will function exactly the same as add.


Used to replace a callback with another callback in an event.

// Replace the "foo" function with the "oof" function
Event::replace('system.post_controller', 'foo', 'oof');

If the event you are replacing does not exist, no event will be added.


Returns of the callbacks as a simple array.

// Returns of the callbacks for system.post_controller
$events = Event::get('system.post_controller');
// Loop through each event and call it
foreach ($events as $event)
    $return_value = call_user_func($event);

If no events exist, and empty array will be returned. It is recommended to use empty if you need to validate that events exist.


Clear one or all callbacks from an event.

// Clears the "oof" function from system.post_controller
Event::clear('system.post_controller', 'oof');

If this method is called without a second argument, it will clear the entire queue for the given event.


Execute all of the callbacks attached to an event.

// Run the system.post_controller event


Checks if an event has already been run. This can is useful to make an event run only once.

// Test if the event has already run
if (Event::has_run('system.post_controller'))
	echo 'post_controller has been run.';
// Run the post controller event if it has not already been run
Event::has_run('system.post_controller') or Event::run('system.post_controller');


Event::$data is a special variable that can be set when using Event::run. The data is assigned by reference, and can be manipulated by all of the callbacks.

$data = Event::$data;
// Debug the data
echo Kohana::debug($data);
// Run the post_controller event with data
Event::run('system.post_controller', $data);
// Display the changed data
echo Kohana::debug($data);

Event data is cleared immediately after all of the callbacks are run, and can only be accessed during callback execution.

« Benchmark : Previous | Next : Kohana »

core/event.txt · Last modified: 2009/05/09 01:30 by lzyy