Learning Kohana

Difficulty: Advanced

• Kohana version: 2.1 and up

Some people have problems understanding the events system and in general I think its wise to dedicate a post on the subject since they’re an intricate part of the Kohana core. Together with hooks (but not necessarily) they have great power and can significantly change the way Kohana works. Do know that in order to work with Kohana you don’t need to use events per se (although Kohana uses them for internal use), Kohana will work flawlessly without events. Only when you want to accomplish some complicated things that hack into the core of Kohana you need to use hooks and events. I’ll cover events and hooks in general in this post and hope to cover a more concrete usage example in the future.

Let me first explain how the hooks system works. It’s fairly simple, you enable the hooks setting in ‘config/hooks.php’ and set $config['enable'] to true. Now you place a file in application/hooks and next time you open a page the hook is loaded and the code in the file is executed.

A hook is just a simple php file that’s included early on in the starting up of Kohana. However, you might want the code to be triggered later on in Kohana. This is where events come in. Events are triggered at several different points in the execution of Kohana. You can find an overview of the different events in the user guide.

Triggering an event is done like this and you can see it happening several times in the Kohana core code. The name of an event is freeform although the ‘prefix.name’ convention is used in Kohana
Triggering events

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

Any callbacks (a call to a function or a class method) that is associated with the event is then launched.

Adding callbacks
‘hooks/foobar.php’

class Foo{
public function bar(){
echo 'foobar';
}
}
Event::add('system.post_controller', array('Foo','bar'));

When the system.post_controller event is trigger in with the Event::run method, Foo::bar is called in the callback. This code will append ‘foobar’ to you output. You can find alternate ways of adding callbacks in the user guide.

There is also a way of changing data with events. See the following example which has no real use but should be self-explanatory.

$data='some string with no capitals';
Event::add('string.capitalize','capitalize');
Event::run('string.capitalize',$data);
echo $data; //echoes 'some string with capitals: Paris, London, Berlin, Amsterdam, Moscow'
 
function capitalize(){
Event::$data=str_replace(' no','',Event::$data);
Event::$data=Event::$data.': Paris, London, Berlin, Amsterdam, Moscow';
}

So, when a second argument is passed in the Event::run() method, it will be available through Event::$data. It’s passed by reference.

I’ll go into a more concrete example next time.