System Events

Event hooks allow you to integrate your custom programming into various places of Bonfire’s execution, without having to modify the core code. Because this is aimed squarely at the developer, and not the end user, there is no GUI to manage this functionality. Instead, registering events is done by modifying a config file.

Summary

System Events	Event hooks allow you to integrate your custom programming into various places of Bonfire’s execution, without having to modify the core code.
Why Is This Better Than CI Hooks?	CodeIgniter’s hooks are a great feature, but they don’t always provide enough flexibility.
Why Not The Database?	There are two primary methods that I can see to store the event data: either in the database, or in a file.
Registering Your Events	In order for events to be ran, they must first be registered in the config/events.php file, by adding your script’s information to the array.
Creating Your Own Events	You can create and use events within your own modules, and they have the same priority and functionality as the System Events.
Available System Event Points

Why Is This Better Than CI Hooks?

CodeIgniter’s hooks are a great feature, but they don’t always provide enough flexibility. There is no documentation on how to create your own hooks (though it’s not that tough), and it lacks the ability to pass any dynamic parameters to the hook. That is the big problem for me. For a modular system like Bonfire, hooks don’t provide any transparent method to support multiple modules.

That’s what System Events aim to solve.

Why Not The Database?

There are two primary methods that I can see to store the event data: either in the database, or in a file. For Bonfire, I chose to use a file-based solution for a couple of different reasons.

First is, oddly enough, performance. On shared hosting, the hard disks are going to be slammed by all of the sites running on the server, that’s true. However, if you are running your site off of shared hosting, the likelihood that you’re really needing to optimize past some page and data caching levels is pretty slim.

Once your traffic is high enough that it warrants moving to a VPS or your own server, you have enough control over the environment that running some form of opcode cache or memcache only makes sense. This moves the slow act of loading the file from the hard drive over to reading the file from the fastest thing possible: RAM, which negates the speed issue.

Besides, databases are generally the bottleneck in your application when it comes to scaling, anyway. Why put another demand on the system if we don’t need to?

The second reason is convenience. In a system like Bonfire, where modules are not enabled in the Admin area, or anywhere else, for that matter, there is no easy way to install a system hook, without having to loop through modules every page load, running install checks. That is a lot of wasted CPU cycles.

Registering Your Events

In order for events to be ran, they must first be registered in the config/events.php file, by adding your script’s information to the array. Each event just needs to know the name of the module, and the controller/library/helper to run, and which event it should be added to.

A sample event would look like

$config['event_name'][] = array(
  'module'        => 'module_name',
  'filepath'      => 'controllers',
  'filename'      => 'my_event.php',
  'class'         => 'MyEvent',
  'method'        => 'my_method'
);

Notes: The declaration works similar to how hooks are defined, though there are a few key differences.

module	The name of the module to find it it. Must be the same as the folder name of the module.
filepath	The path to the file within the module’s folder. This allows you to use any controller, library, or helper file for your event.
filename	The name of the file to load. Must include the file extension.
class	The name of the class to create an instance of.
method	The name of the method within the class to call.

Most system events will deliver a payload. This will typically be an array of data that the event allows you to operate on. Each payload will be described in the event descriptions below.

Creating Your Own Events

You can create and use events within your own modules, and they have the same priority and functionality as the System Events. It is a simple matter of calling the trigger() method from your controller or library.

Events::trigger('event_name', $payload);

When this method is called, it searches the events array for any matching events and runs them.

Available System Event Points

Controllers

before_controller	Called prior to the controller constructor being ran. Payload is the name of the current controller.
after_controller_constructor	Called just after the controller constructor is ran, but prior to the method being ran. Payload is the name of the current controller.

Templates and Pages

after_page_render	Called just after the main view is rendered. Payload is the view’s output.
after_layout_render	Called just after the entire page is rendered. Payload is the current output.
after_block_render	Called just after the block is rendered. Payload is an array with ‘block’ being the name of the block and ‘output’ being the rendered block’s output.

Users

after_login	Called after successful login. Payload is an array of ‘user_id’ and ‘role_id’.
before_logout	Called just before logging the user out. Payload is an array of ‘user_id’ and ‘role_id’.
after_create_user	Called after a user is created. Payload is the new user’s id.
before_user_update	Called just prior to updating a user. Payload is an array of ‘user_id’ and ‘data’, where data is all of the update information passed into the method.
after_user_update	Called just after updating a user. Payload is an array of ‘user_id’ and ‘data’, where data is all of the update information passed into the method.