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.

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 prefix.name to make event names more unique. All pre-defined events are prefixed as system.name, 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
Event::run('system.post_controller');

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 »