Khaos :: KhEvent

[eluser]Neophyte[/eluser]
Updated - 21/04/2008 - Download - Khaos::KhEvent - 0.2

Introduction
This library lets you have various events throughout your application for anything you want, some common examples would be events such as user login, logout, authenticate etc.. Once these events are in place you can create observers which are automatically called whenether the event is triggered. This lets you easilly extend your application without having to change your core code as it doesnt need to know any specifics about the observers.

Sample Usage
The best example is probably a user system where you can trigger events for user login, logout, creation, deletion and modification. Observers can then be created utilising these events such as an observer for phpbb allowing you to login, logout, create and delete users from phpbb without having to edit your controller or model files.

Quick Reference

Code:

/*
* KhEvent
*
* array  trigger ( string $event[, array $args] )
* void   register ( string $event, callback $handler )
*/

// Example Trigger
$results = $this->khevent->trigger('onLogin', array('username', 'password'));

// Example Register
$this->khevent->register('onLogin', array(&$this, 'login'));

Pre-Defined Events
onPreController
onPostControllerConstructor
onPostController
onPostSystem

Configuration
KhEvent will work right out the box aslong as the system/cache folder is writable. However if you wish to change the behaviour of KhEvent then create the config file khaos.php.

Below is a sample config which represents the default behaviour of KhCache.

Code:

$config['event'] = array(
    'directory' => 'observers',
    'autoscan'  => true
);

everything in the config file is optional so options only need to be specified if you wish to override the default behaviour.

directory - Directory relative to the application path where all the observer files are held (the directory can contain sub folders to aid with organisation)

autoscan - When set to true if you make a change to an observer the observer map cache is automatically updated when set to false you need to manually delete the kh_event_map file in the cache folder if you make a change to the observers directory.

[eluser]xwero[/eluser]
How is this different from the hooks functionality?

[eluser]Neophyte[/eluser]
[quote author="xwero" date="1201212670"]How is this different from the hooks functionality?[/quote]
bare in mind ive only been using CI for a few days so am far from familiar with the hooks system but to me the hooks system appears to be a way to adjust application flow and not an usable way of dealing with events. eg. in a user library i want to let other scripts be notified of certain events, user login, logout, creation, deletion, modification etc ... so below is how i'd go about it with the hooks approach and the above approach.

Hooks
I wish to log a user in so i do my usual login code and now i want to give other applications a chance to login using the same credentials say phpbb so i invoke $this->hooks->_call_hook('user_login'); and thats where i get stuck, how would you pass the user credentials as the params are fixed in the config/hooks.php config file for each hook, as best as i can see anyway. Assuming this wasnt a problem i'd want to see how each of the scripts phpbb etc responded and if any failed maybe abort the login or log a message though just scanning the code the return data doesnt appear to be captured or returned when you call a hook.

Events
The login method of the user library is called and again i do any usual login stuff and then use the following line to notify any interested scripts that a user is logging in

Code:

$results = $this->event->trigger('onUserLogin', array($username, $password));

each of the plugins listening for this event is now called and passed the users login credentials and passes back whether or not they where successful in logging in. an example might be a plugin called phpbb.php with the method onUserLogin which creates the phpbb session record.

The user library login method now iterates over the results array looks for any problems in logging the user in if no problems arise it continues as normal if any of the plugin methods return an error i can choose to log the user out or just report a message or raise another event asking scripts to re-create/fix the users login etc ..

[eluser]wiredesignz[/eluser]
Very cool idea, Thanks Neophyte.

[eluser]Rick Jolly[/eluser]
Very interesting. This is what I think I understand: Instead of calling a plugin method directly from your application, you trigger an event and it is the job of the plugin to implement a method to accept that event if desired. That isolates the application from the plugin(s). Excellent way to make a more modular application.

Could you explain how the pre-registered events work? Wouldn't I have to register a class and method to use any of those pre-registered events much like your example to register a custom event. In that case, couldn't the same thing be done using hooks (albeit in a less transparent way).

[eluser]Majd Taby[/eluser]
From what I picked up, the idea seemed interesting, i'm not exactly sure how it's useful though. What gets notified of an event, what's an event?

[eluser]wiredesignz[/eluser]
hooks/khaos/plugins.php is autoloaded and intercepts CI's standard hooks as above, but you can register your own user events and trigger them at some stage later.

libraries/khaos/events.php is include()'d above and each plugin is loaded via the config/khaos.php $config['plugins'] array and registers itself with the event dispatcher.

The event listener intercepts the events and the appropriate plugin/functions() will run when a system_event (hook) is triggered or a user registered event is triggered by you.

Hope this helps. (this was just a quick look over the code, I may have missed something)

[eluser]Neophyte[/eluser]
My explanations always let me down heh

Could you explain how the pre-registered events work? Wouldn’t I have to register a class and method to use any of those pre-registered events much like your example to register a custom event. In that case, couldn’t the same thing be done using hooks (albeit in a less transparent way).

wiredesignz post just above mine gives an excellent run down of whats going on but just to clarify the power of the library comes in setting up your own events (as you pointed out) and it was only a small amount of code to add the CI hooks as events so i did.

As a quick example of how it could come in handy the SMF forum lets you track whos online accross your entire site just by calling one of their functions so if you had an smf plugin listening to the usual sort of events of your user system, login, logout, create etc ... you could also add the method onPreController() to your plugin which would be called every page view in which you could update the whos online of SMF, this would keep everything to do with integrating your application with SMF in the same smf.php file and save you setting up another hook.

In response to Zaatar i think Rick Jolly's first paragraph sums it up nicely

Very interesting. This is what I think I understand: Instead of calling a plugin method directly from your application, you trigger an event and it is the job of the plugin to implement a method to accept that event if desired. That isolates the application from the plugin(s). Excellent way to make a more modular application.

and again wiredesignz more technical explanation should help

[eluser]wiredesignz[/eluser]
I think its a great addition to my CI armoury, I havent really seen anyone use Plugins with CI yet, this might generate some new ideas.

[eluser]Crafter[/eluser]
This looks great. I see a lot of potential here and I plan to look at it further shortly. Thanks for sharing.