Signal and Events

When you create a small Pluf application, most of the time you want to give the ability for the people integrating it into their own project to customize it. You know how to do it with the templates but you can also enable hooks to allow code execution at given point in your application.

What Are Signals

Signals are just a way to broadcast to all the installed applications that a given event is happening and that if an application wants to do something at this point it is possible.

For example, you have a mailing list application, you can create a signal to inform all the applications that you are sending an email and give as argument the content of the email. The other application, for example a statistics application, could modify the content of the email to add tracking information in the links.

How to be the Provider

This is very simple:

$params = array('bingo' => $bingo,
                'user' => $user);
Pluf_Signal::send('the_name_of_the_signal',
                  'YourApp_YourClass', $params);

Nothing more! What does it means? The array $params is storing the parameters you want to send to the applications listing to your signal. This array is passed by reference.

When you send a signal, it has a name, here the_name_of_the_signal and a sender which is the name of the class from which you send the signal, here YourApp_YourClass.

By convention, the name of the signal is YourClass::methodSending-extrainfo.

How to Act on a Signal

This is a bit more complex as you need to do 2 things:

1. Register a listener for a given signal;
2. Provide the code of the listener.

Usually you register your listener either in the relations.php file of the application listening or in your configuration file.

The registration is done that way:

Pluf_Signal::connect('the_name_of_the_signal',
      array('YourApp_YourClass', 'methodHandlingTheSignal'));

or optionally, you can add the restriction to listen to a given signal, but only if sent by a given sender.

Pluf_Signal::connect('the_name_of_the_signal',
      array('YourApp_YourClass', 'methodHandlingTheSignal'),
      'OtherApp_TheClass');

The signature of the method handling the signal is:

class YourApp_YourClass
{
    static function methodHandlingTheSignal($signal, &$params)
    {
        // Do something with $params
    }
}

Signal Documentation

In your code, you can document your signal to be able to easily generate a list of signals as part of your software documentation. The documentation is a simple comment block starting with /** with each line starting with a star *. Inside it, 4 comment sections are required, each starting with its name in square brackets [section].

The sections are:

• signal: the name of the signal;
• sender: the sender of the signal;
• description: the description of the signal;
• parameters: the parameters of the signal.

Here is an example of signal description taken from an existing application, as you can read, the signal itself is defined just after the documentation block.

/**
 * [signal]
 *
 * Pluf_User::passwordUpdated
 *
 * [sender]
 *
 * IDF_Form_RegisterConfirmation
 *
 * [description]
 *
 * This signal is sent when the user updated his
 * password from his account page.
 *
 * [parameters]
 *
 * array('user' => $user)
 *
 */
$params = array('user' => $this->_user);
Pluf_Signal::send('Pluf_User::passwordUpdated',
                  'IDF_Form_RegisterConfirmation', $params);

Workflow at the Framework Level

When you run Pluf::start() the configuration file and all the relations.php files are loaded. This means that all the Pluf_Signal::connect calls are performed and the signal listeners are registered.

When a signal is sent, Pluf will check the list of listeners and dispatch the signal to the listeners. The listeners are called in the order of registration.

Report issues in the documentation

If you find errors or issues in the documentation, report a bug. We will update the documentation accordingly.