*IMPORTANT*

The observers mechanism was modified to use the new package [http://pear.php.net/package/Event_Dispatcher Event_Dispatcher] in version [http://pear.php.net/package/LiveUser 0.15]. **If you were using observers with version 0.14 please check this example and update your code accordingly**

----

When using an authentication and permission management one might need to implement custom functionalities. Since it is impossible to provide all features as built-in Matthias Nothhaft stepped up and implement observers into LiveUser.

Observers will be notified about key changes of state in the LiveUser object. Observers make it possible to extend the feature LiveUser provide to implement any scheme you may have.

You can use observers to have added security upon login (IP address restrictions), improve the data gathering process (upon login you can save the data) and several other possibilities. There are no limits to what you can do, an observer is a simple class or function which gets notified when an event is triggered.

An observer code example is shown below.

++ Events list

: 'onLogin'       : successfully logged in
: 'forceLogin',   : login required -> you could display a login form
: 'onLogout',     : before logout -> can be used to cleanup own stuff
: 'postLogout',   : after logout -> e.g. do a redirect to another page
: 'onIdled',      : maximum idle time is reached
: 'onExpired'     : authentication session is expired
: 'onFailedLogin' : login failed
: 'onUnfreeze'    : successfully unfreeze of a previously logged in user

++ How to use observers

 An observer will receive a [http://pear.php.net/manual/en/package.event.event-dispatcher.event-notification.event-notification.php notification object]. Using observers is done via a simple call to a public method of the LiveUser class. One method is available to attach observers:

[http://pear.php.net/manual/en/package.event.event-dispatcher.event-dispatcher.addobserver.php $liveuser_object->dispatcher->addObserver] expects a PHP callback. That means you may either pass a function name as a string or an array containing an object or class and a method to call.

[http://pear.php.net/manual/en/package.event.event-dispatcher.event-dispatcher.addobserver.php See this] for further explanation.

++ Observer class example

<code type="php">
/**
 * LiveUser observer example.
 *
 * @access public
 * @param  object receives a notification object, fetch it by reference 
 *                to avoid object copies
 * @return void  return is discarded
 */
class LU_Default_observer
{
    /**
     * This method will receive all the events fired
     *
     * @param  object  a Event_Notification object
     * @return void
     */
    function notify(&$notification)
    {
        echo "observer called on event: " 
        . $notification->getNotificationName() . " n";
    }
}

// Create new LiveUser (LiveUser) object.
// WeŽll only use the auth container, permissions are not used.
$LU  =& LiveUser::factory($liveuserConfig);
$obs = new LU_Default_observer();
$LU->dispatcher->addObserver(array(&$obs, 'notify'));
</code>

++ How to add new events

If you write a class which extends LiveUser you can use the following code

<code type="php">
class MyClass extends LiveUser
{
    function MyClass()
    {
    }

    function customMethod()
    {
        $this->dispatcher->post($this,'onMyCustomEvent');
    }
}
</code>