Event Class

The event class allows you to interact with the Fuel Core without having to alter any core files.

System defined events

The FuelPHP defines several events on the fuelphp instance, which you can use to hook into the core without having to extend it. These events are:

Event Description
app_created This event will be triggered after the FuelPHP framework has been initialised.
request_created This event will be triggered after a new Request object has been forged.
request_started This event will be triggered when execution of a Request is requested.
controller_started This event will be triggered before the controllers before() method is called.
controller_finished This event will be triggered after the controllers after() method has been called and the response received.
response_created This event will be triggered after a new Response object has been forged.
request_finished This event will be triggered when execution of a Request is complete and a response is received.
shutdown This event will be triggered after the main request has been processed and the output has been send out.
 
Example In app/config/event.php 
<?php

return array(
    'fuelphp' => array(
        'app_created' => function()
        {
            // After FuelPHP initialised
        },
        'request_created' => function()
        {
            // After Request forged
        },
        'request_started' => function()
        {
            // Request is requested
        },
        'controller_started' => function()
        {
            // Before controllers before() method called
        },
        'controller_finished' => function()
        {
            // After controllers after() method called
        },
        'response_created' => function()
        {
            // After Response forged
        },
        'request_finished' => function()
        {
            // Request is complete and Response received
        },
        'shutdown' => function()
        {
            // Output has been send out
        },
    ),
);

Class methods

register($event, $callback)

The register method allows files to register an object that will be run when the trigger method is called.

Static Yes
Parameters
Param Default Description
$event required The event you are registering your code to.
$callback required The callback method.
Returns boolean
Example 
Event::register('user_login', 'Class::method');

unregister($event, $callback = null)

The unregister method allows files to unregister an object that would be run when the trigger method is called.

Static Yes
Parameters
Param Default Description
$event required The event you are registering your code to.
$callback optional The callback method. If none provided all callbacks will be removed.
Returns boolean
Example 
// Define two even calbacks
$callback_one = function()
{
    echo 'callback one';
}

$callback_two = function()
{
    echo 'callback two';
}

// Register the events to "my_event"
Event::register('my_event', $callback_one);
Event::register('my_event', $callback_two);

// Unregister callback one
Event::unregister('my_event', $callback_one);

// Trigger the event
Event::trigger('my_event');
// This will only echo "callback two"

// Unregister all callbacks from "my_event";
Event::unregister('my_event');

// Trigger the event
Event::trigger('my_event');
// Will output nothing.

trigger($event, $data = '', $return_type = 'string', $reversed = false)

The trigger method is used to trigger or activate callbacks that are associated through the register method.

Static Yes
Parameters
Param Default Description
$event required The event you are triggering.
$data 
''
 Any data you want to send to the method registered.
$return_type 
'string'
 What type of return data you expect. (string, array, json, none, serialized) - Default is string
$reversed 
false
 Set to true to fire the events in reversed order, LIFO instead or FIFO.
Returns mixed - Dependent on the $return_type.
Example 
Event::trigger('user_login', $data)

has_events($event)

The has_events method is available so you can check if a particular registered event has triggers.

Static Yes
Parameters
Param Default Description
$event required The event you are checking.
Returns boolean
Example 
Event::has_events('user_login')

forge(array $events = array())

The forge returns a new event object.

Static Yes
Parameters
Param Default Description
$events 
array()
 The event you are checking.
Returns Event_Instance object
Example 
// Create a new event object
$events = Event::forge();

// Create a new event object
// with events
$events = Event::forge(array(
    'update' => function(){
        // do something on update
    },
    'register' => function(){
        // do something on register
    },
));

/**
 * !! All other Event method apply to the instance
 */
$events->register('my_event', function(){
    echo 'this is awesome';
});

$events->trigger('my_event');
// will output "this is awesome"

instance($name = 'fuelphp', array $events = array())

The instance returns a new event object singleton.

Static Yes
Parameters
Param Default Description
$name 
'fuelphp'
 The instance name.
$events 
array()
 The event you are checking.
Returns Event_Instance object
Example 
// Create a new event instance
$events = Event::instance('my_instance');

$same = Event::instance('my_instance');

$events->register('my_event', function(){
    echo 'awesome!';
});

$same->register('my_event', function(){
    echo 'this is ';
});

Event::instance('my_instance')->trigger('my_event');
// will output "this is awesome!"