^Status|Draft|
^Todo|Proof read|

====== Event Class ======

For a programming overview of events, please see [[wp>Event_handler]] and [[wp>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 [[http://php.net/manual/en/language.pseudo-types.php#language.types.callback|callback]]. By default, there are several [[general:events|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''.


===== Methods =====

All Event methods are [[http://php.net/manual/en/language.oop5.static.php|static]], and Event should never be instanced.

==== add ====

Used to add a new [[http://php.net/manual/en/language.pseudo-types.php#language.types.callback|callback]] to an event. If the event does not already exist, it will be created.

<code php>

// 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'));

</code>

You can also create entirely new events this way:

<code php>

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

</code>

==== add_before ====

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

<code php>

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

</code>

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

==== add_after ====

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

<code php>

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

</code>

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

==== replace ====

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

<code php>

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

</code>

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

==== get ====

Returns of the callbacks as a simple array.

<code php>

// 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);
}

</code>

If no events exist, and empty array will be returned. It is recommended to use [[http://php.net/empty|empty]] if you need to validate that events exist.

==== clear ====

Clear one or all callbacks from an event.

<code php>

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

</code>

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

==== run ====

Execute all of the callbacks attached to an event.

<code php>

// Run the system.post_controller event
Event::run('system.post_controller');

</code>

==== has_run ====

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

<code php>

// 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');

</code>

===== Data ====

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

<code php>
$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);

</code>

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

<html><p style="text-align:center"></html><< [[core:benchmark|Benchmark]]<html> : Previous | Next : </html>[[core:kohana|Kohana]] >><html></p></html>