Libraries

Events Library

This is a very small library which will help you better organize actions or “events” that occure at particular parts/sections of your application. A perfect example would be a subscription system where after a person has suscribed you would want to log something, or notify someone of their subscription. Events can do this in a very simple and elegant manner.

Important: You must create a new folder within your application or modules folder called handlers.

Config Event Loading

If you would like to preset events to be loaded without having to place them into each controller you may do so by doing the following:

$events['autoload'] =
   array(
      array('event' => 'on_system_load','callback' => 'on_system_load' [, 'module' => 'module' ])
   );

Important: You will need to add a new file called events.php into your application/config/ folder.

Usage Example

The Events library is very simple to use. Here is a small example of using the Events library while processing a user subscription to a website or a service. Before starting please make sure that you have the handlers folder which should be located in your application or application/modules folder.

Start by creating a controller. In this example I will only create a small example, which may not be functional in real world testing.

We are calling this controller Subscribe which will be placed in application/controllers/Subscribe.php

class Subscribe extends Controller
{
   function Subscribe()
   {
      parent::Controller();
      // load the library dahhhh!
      $this->load->library('events');
      // register the event and its callback function which will be triggered later.
      $this->events->register('on_subscribe_new','on_subscribe_new');
   }

   function add($email)
   {
      if (valid_email($email))
      {
         /*
         * Here you would make sure that the email gets added to the database and the user is notified of their addition to the list.
         * Once you have done that you can then use the Events library to trigger an event, in this case when the subscriber is added
         * we are going to notify another user of the system.
         */

         // create array to be passed to trigger function
         $data = array('new_subscriber' => $email, 'notify' => 'example@example.com');
         // trigger event.
         $this->events->trigger('on_subscribe_new',$data);
      }
   }
}

Now we are going to build the handler for this event. Create a new file the handler and place it into the handlers folder like so application/handlers/on_subscribe_new.php folder.

If you are not using the modular option for events, all your event callback functions need to be prefixed with event_handle_, while if you use the modular option prefix them with module_handle_. This is to void having duplicate events or events clashing throughout a big application or site.

function event_handle_on_subscribe_new($params)
{
   /*
   * From here we can do anything to the data that is being passed from the controller.
   * This gives us great power over the code and is more controllable then being left in
   * the controller itself.
   */
   if (is_array($params))
   {
      $subscriber = element('new_subscriber',$params);
      $send_to = element('notify',$params);

      if (!empty($subscriber) AND !empty($send_to))
      {
         $this->email->from('subscribe@example.com');
         $this->email->to($send_to);

         $this->email->subject('New Subscriber for [example.com]');

         $this->email->message('You have a new subscriber to example.com Email: '.$subscriber.' You are getting more popular!');

         $this->email->send();
      }
   }
}

More Examples

Example of registering a single event with single callback function

$this->events->register('event','callback');

This is the very simple use of the library. It is very straight forward. Location of your handlers would now be in application/handlers.

Example of registering an event and callback function within a module

$this->events->register('event','callback','module');

This is the very simple use of the library. It is very straight forward. Important:  Your callback function would now be located at application/modules/module/handlers/my_callback_function.php.
If you ever use multiple events with multiple callback functions and append a module name to it, all the callback functions must be located within that module.

Example of registering multiple events with single callback function

$this->events->register(array('event_one','event_two','event_three'),'callback'); OR $this->events->register('event_one,event_two,event_three','callback');

In this example all three (3) events will trigger the one callback function.

Example of registering a single event, with multiple callback functions

$this->events->register('event',array('callback_one','callback_two','callback_three')); OR $this->events->register('event','callback_one,callback_two,callback_three');

In this example all three (3) callbacks will be called when the event is triggered.

Events Library Function Reference

$this->events->register( mixed $event, mixed $callback [, string $module]);

This is the function used to register an event with its associated callback functions. Paramaters for the event name and callback functions can be passed in three (3) types; array, list or string

$this->events->trigger( string $event, array $paramaters);

This function will trigger the event name with its associated callback function. Passing paramaters can be set to NULL and passed to the callback functions. Paramaters are expected to be in array format.