Gabriel¶

What does it do?¶

Gabriel is a scheduling engine that lets other extensions schedule events to happen at a specific or recurring time. Gabriel will then make sure the event is executed.

For now Gabriel is only executed thorugh a script intended to be run from a cronjob. It is the intention to have a real daemonized script to do the same as well as scripts executed depending on webserver hits, this way the scheduling will work in any hosting environment, and still have the option of real-time execution for those with those needs. The client extensions however never needs to worry about this.

Implementing functionality¶

In order to make use of gabriel as scheduling engine in your own extension, you need to create a class that extends the event class and implements the execute method. Very simple.

There is one concern to beware of though. Gabriel uses the constructor of the event to class to iniate a reference to the global singleton instance of the main Gabriel class. in PHP5 this works without any problems, but in PHP4 the constructor of the base class is not called upon construction of derived class. In order to ensure PHP4 compatibility you therefore need to make a constructor of your class that is a wrapper for the real PHP5-style constructor of the base class, like this:

class tx_sysworkflows_notification extends tx_gabriel_event {

/*** PHP4 wrapper for constructor**/function tx_sysworkflows_notification() {$this->__construct();}

}

You can add as many methods and properties as you want, but please consider if it's really part of the event itself. It might make sense to put functionality in a seperate class and aggregate the two. This will also make your extension more robust to future changes in the event base class.

The class contains a little information which is maintained by gabriel and that might be useful to you.

The property *eventUid* is the unique identification of the event, and enables you to refetch the event at some point in the future.

The property *executionTime* is set to the timestamp of the next due execution of the event upon storing to the database. This is the timestamp that will make gabriel fetch it and execute it which means that upon excution the property will contain the timestamp that caused the execution, which might be helpful information.

One important thing to be aware of is that since the execution of events is notcontinuous, it might happen that several execution times have passed before the gabriel cron script is executed. In this case the event will only be executed once . If you have a scenario where this is a problem, get in contact with me, I might consider implementing support for other behaviour.

Making sure your scripts are included¶

You need to make gabriel aware of any derivative of the event class. This is necessary because the script needs to be loaded in PHP when restoring the objects from the database. And gabriel makes sure to include all needed scripts.

In your extension make sure there is a ext_localconf.php file and add something along the line of

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['gabriel']['include'][$_EXT KEY] = 'class.tx_sysworkflows_notification.php';

This will make gabriel include your script. Make sure the value is relative to the root of your extension. In other words if your script is located in a subfolder, make sure to prefix that.

If you have more than event derivative in your extension, you can add the entries as an array, like this:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['gabriel']['include'][$_EXT KEY] = array('class.tx_sysworkflows_notification.php','examples/clas s.tx_sysworkflows_eventexample.php'

);

Scheduling events¶

Once you have your event class implemented, you are ready to schedule instances of it.

So first thing is to make yourself an instance of your class, like

$notification = t3lib_div::getUserObj('EXT:sys_workflows/class.tx_ sysworkflows_notification.php:tx_sysworkflows_notification')

next thing schedule some executions:

$notification->registerRecurringExecution(strtotime('+ 1 minute'),10,strtotime('+ 1 day'));$notification->registerSingleExecution(strtotime('december 24 2005'));

And then you need to tell gabriel about it. Gabriel is designed to be running as a singleton instance, in TYPO3 this is done by prefixing an & to the classname (well that's not a real singleton, but it's close enough :D), always make sure you get your gabriel instance that way:

$gabriel = t3lib_div::getUserObj('EXT:gabriel/class.tx_gabriel.php: &tx_gabriel');

And then add the event to the cue:

$gabriel->addEvent($notification,'test from sys_workflow @' .time());

And your all set.