Zeta Components - high quality PHP components

Tutorial
API

eZ Components - SignalSlot

Introduction
Class overview
Usage

Introduction

The SignalSlot component implements a mechanism for inter- and intra-object communication through the use of signals and slots. Signals are emitted through instances of the ezcSignalCollection class and connected to as many functions as needed. A function that is connected to a signal is called a slot. When the signal is emitted, all connected slots will be run in the order they are connected or in the order of the priorities specified when connecting to the signals.

The SignalSlot library supports signals with arguments that are passed on to the slot. Slots must accept all the parameters that are sent to it. The SignalSlot component also supports prioritized slots. Using this mechanism, you can ensure that a slot is run either before or after other slots.

There are many different variations of the Signal/Slot model. The original implementations required you to derive from the Signal class in order to have signals or slots. This is acceptable for languages that support multiple inheritance. Newer implemtentations circumvent this problem by representing signals through one instance of the Signal class. In other words, a class that has two signals will have two member variables holding instances of the Signals class. This approach can lead to the creation of a lot of signal objects, which can be especially problematic for scripting languages. As a result, our signal class can represent several signals.

Class overview

This section gives you an overview of the main classes in the SignalSlot component.

ezcSignalCollection: This class represents a collection of signals. You can emit or connect to the signals using the methods available in this class.
ezcSignalStaticConnections: This class holds the static connections for your application. Static connections are connections to signals that can be emitted by several different instances of ezcSignalCollection.

Usage

A simple signal

This first example shows the simplest possible usage of the signal system. We simply create a new ezcSignalCollection class, connect the "sayHello" signal to the function "hello" and emit the signal.

<?php
require_once 'tutorial_autoload.php';
function hello()
{
echo "Hello world\n";
}
$signals = new ezcSignalCollection();
$signals->connect( "sayHello", "hello" );
$signals->emit( "sayHello" );
?>

The output of this example yields the classic "Hello world".

Slot types

Slots are not limited to normal functions. They are specified using the pseudo type callback. You can specify normal functions, class methods and static class methods, as shown by these variations of the above example.

functions

<?php
require_once 'tutorial_autoload.php';
function hello()
{
echo "Hello world\n";
}
$signals = new ezcSignalCollection();
$signals->connect( "sayHello", "hello" );
$signals->emit( "sayHello" );
?>

class methods

<?php
require_once 'tutorial_autoload.php';
class HelloClass
{
public function hello()
{
echo "Hello world\n";
}
}
$signals = new ezcSignalCollection();
$signals->connect( "sayHello", array( new HelloClass(), "hello" ) );
$signals->emit( "sayHello" );
?>

static class methods

<?php
require_once 'tutorial_autoload.php';
class HelloClass
{
public static function hello()
{
echo "Hello world\n";
}
}
$signals = new ezcSignalCollection();
$signals->connect( "sayHello", array( "HelloClass", "hello" ) );
$signals->emit( "sayHello" );
?>

Signals in a class

The typical usage of signals is to have classes emit them when certain events occur. The following example shows a data object that emits a signal when its data is changed. The signal is connected to the caching system, which clears the cache when the data is changed.

This example also shows how you can delay the construction of the ezcSignalCollection object. This can be useful in applications where signals are rarely used and you want to avoid the overhead of creating the object.

<?php
require_once 'tutorial_autoload.php';
class Data
{
private $signals = null;
public function signals()
{
if ( $this->signals == null ) $this->signals = new ezcSignalCollection();
return $this->signals;
}
public function manipulate()
{
// change the data here
$this->signals()->emit( "dataChanged" );
}
}
class Cache
{
public function deleteCache()
{
echo "Deleting cache\n";
}
}
$cache = new Cache();
$data = new Data();
$data->signals()->connect( "dataChanged", array( $cache, "deleteCache" ) );
$data->manipulate();
?>

Signals with parameters

Signals can have parameters that will be passed on to the receiving slots. The next example is an extension of the previous example, where the data object gives some information about the data that was changed. This information is passed to the receiving slots as a parameter.

<?php
require_once 'tutorial_autoload.php';
class Data
{
private $signals = null;
public function signals()
{
if ( $this->signals == null ) $this->signals = new ezcSignalCollection();
return $this->signals;
}
public function manipulate()
{
// change the data here
$this->signals()->emit( "dataChanged", "calendar" );
}
}
class Cache
{
public function deleteCache( $type )
{
echo "Deleting cache for ID: {$type}\n";
}
}
$cache = new Cache();
$data = new Data();
$data->signals()->connect( "dataChanged", array( $cache, "deleteCache" ) );
$data->manipulate();
?>

Note that slots must accept the parameters that are passed to them. You will get errors / warnings if you provide too few parameters to the slots you have connected to a signal.

Also note that it is not possible to pass signal parameters by reference except for object types, which are always references in PHP 5.

Multiple slots

It is possible to connect several slots to one signal. This is just a matter of calling "connect" several times. You can freely mix the different slot types. The following example adds another connection to our previous example. It regenerates the cache after it has been deleted.

<?php
require_once 'tutorial_autoload.php';
class Data
{
private $signals = null;
public function signals()
{
if ( $this->signals == null ) $this->signals = new ezcSignalCollection();
return $this->signals;
}
public function manipulate()
{
// change the data here
$this->signals()->emit( "dataChanged", "calendar" );
}
}
class Cache
{
public function deleteCache( $type )
{
echo "Deleting cache for ID: {$type}\n";
}
}
class CacheGenerator
{
public function generateCache( $identifier )
{
echo "Generating cache for ID: {$identifier}\n";
}
}
$cache = new Cache();
$cacheGenerator = new CacheGenerator();
$data = new Data();
$data->signals()->connect( "dataChanged", array( $cache, "deleteCache" ) );
$data->signals()->connect( "dataChanged", array( $cacheGenerator, "generateCache" ) );
$data->manipulate();
?>

Prioritized slots

The previous example showed how to connect several slots to one signal and how they are executed one after another. The example code is also dependent on the order the slots are executed. Normally, slots are executed in the order they are connected. Sometimes, it is not possible to connect slots in the order you want them to be executed. To ensure that some slots are executed before others, you can use the priority system. When connecting, you can specify a priority for that connection. Priority numbers can be specified using any positive integer. The lower the number, the higher the priority. Higher priority connections are executed first. By default, connections are made with a priority of 1000.

This example shows how the connections from the previous example could have been specified to ensure the order in which the slots are called.

<?php
require_once 'tutorial_autoload.php';
class Data
{
private $signals = null;
public function signals()
{
if ( $this->signals == null ) $this->signals = new ezcSignalCollection();
return $this->signals;
}
public function manipulate()
{
// change the data here
$this->signals()->emit( "dataChanged", "calendar" );
}
}
class Cache
{
public function deleteCache( $type )
{
echo "Deleting cache for ID: {$type}\n";
}
}
class CacheGenerator
{
public function generateCache( $identifier )
{
echo "Generating cache for ID: {$identifier}\n";
}
}
$cache = new Cache();
$cacheGenerator = new CacheGenerator();
$data = new Data();
$data->signals()->connect( "dataChanged", array( $cacheGenerator, "generateCache" ), 20 );
$data->signals()->connect( "dataChanged", array( $cache, "deleteCache" ), 10 );
$data->manipulate();
?>

Excessive usage of the priority system can lead to unmaintainable code, since it is hard to track the various priorities that are in use in a system. We do not recommend using it unless absolutely neccessary.

Static connections

Sometimes it is useful to connect a signal with a specific name, regardless of the sender ezcSignalCollection, to a slot. Consider what would happen if the Data class from our previous example was extended to a DataObject class with a potential of thousands of instances. If you wanted the caching system to work, you would have to connect each one to the caching system upon creation.

This is both unpractical and time consuming. The solution is to use static connections. When creating ezcSignalCollection objects, you can provide an identifier to the constructor. Using ezcSignalStaticConnections, you can connect to all signals from a source with a specific identifier.

The following example shows how to use static connections to connect the signal "dataChanged" from all objects of the type "DataObject" to the caching system.

<?php
require_once 'tutorial_autoload.php';
class DataObject
{
private $signals = null;
private $identifier = null;
public function __construct( $id )
{
$this->identifier = $id;
}
public function signals()
{
if ( $this->signals == null ) $this->signals = new ezcSignalCollection( __CLASS__ );
return $this->signals;
}
public function manipulate()
{
// change the data here
$this->signals()->emit( "dataChanged", $this->identifier );
}
}
class Cache
{
public function deleteCache( $identifier )
{
echo "Deleting cache for ID: {$identifier}\n";
}
}
$cache = new Cache();
ezcSignalStaticConnections::getInstance()->connect( "DataObject",
"dataChanged", array( $cache, "deleteCache" ) );
$data1 = new DataObject( 1 );
$data2 = new DataObject( 2 );
$data1->manipulate();
$data2->manipulate();
?>

You can freely mix static connectons and normal connections. Static connections with the same priority as normal connections are executed after the normal connections.

Lazy initialization

Lazy initialization is a mechanism to load and configure a component, only when it is really used in your application. This mechanism saves time for parsing the classes and configuration, when the component is not used at all during one request. You can find a description how you can use it for your own components and how it works in the ezcBase tutorial. The keyword for the signal slot component is ezcInitSignalStaticConnections.

<?php
require_once 'tutorial_autoload.php';
class customLazySignalConfiguration implements ezcBaseConfigurationInitializer
{
public static function configureObject( $signal )
{
$signal->connect( 'default', 'signal', 'customFunction' );
}
}
ezcBaseInit::setCallback(
'ezcInitSignalStaticConnections',
'customLazySignalConfiguration'
);
function customFunction()
{
echo "Custom function called with:\n", var_export( func_get_args(), true );
}
$signals = new ezcSignalCollection();
$signals->emit( 'signal', 42 );
?>

This example shows a very simple signal setup with only one signal mapped to a custom function, which just dumps the passed data. The main difference, compared to earlier examples, is that we roll out the configuration to an own class, and define a callback using ezcBaseInit::setCallback to this class, which will be called with the static connections manager as a parameter on the first request for a yet uninitialized signal connection.

ezcBaseInit::setCallback accepts as a first parameter a component specific key, which lets the component later request the right configuration callback. This class must implement the ezcBaseConfigurationInitializer class. The second parameter is the name of the class to perform the static callback on. Each component's lazy initialization calls the static method configureObject() on the referenced class.

When a signal connection is really created and used, like shown in line 22 of the example, the collection will be configured by the custom configuration class. The used identifier "default" may be used for the default signal collection. It of course works for other signal collections, too, like the example for static connections shows.