Xaraya | M.R. van der Boom |
Request for Comments: 0041 | F. Besler |
Category: Best Current Practice | Xaraya Development Group |
February 2003 |
RFC-0041: Event handling system
This document specifies a Xaraya Best Current Practices for the Xaraya Community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited.
Copyright © The Digital Development Foundation (2003). All Rights Reserved.
1 This RFC describes the event messaging system used by Xaraya to date. The different core packages may register events and trigger them at a certain point in the system load process. The modules may define event handlers to react to these events.
eventlist | missing | open | 2003-02-27 | marcel@hsdev.com |
package dependencies | needs | open | 2003-02-27 | marcel@hsdev.com |
2 In this RFC the mechanisms will be described which are currently used in the event messaging system of Xaraya.
3 The event system is used by core packages of Xaraya to trigger certain events in the system. These events are dispatched to the active modules which can define special functions which can then act on those events.
4 This system co-exists with the hooks system. They are alike but the main reasons to have a separate event-system next to the hook system are:
7 AnySome core packages can define events, also known as registering them, by calling the function.
xarEvt_registerEvent($eventName)in its initialization function. This function registers the name of the event in a global variable. The only place that this function may be called is in a core package initialization part. This can be checked with bk -r grep xarEvt_registerEvent.
8 Not all core packages can register events, for example the exception system cannot. The reason for this is that the exception system cannot depend on anything but the basics in Xaraya.
I package dependencies (type: needs, status: open) | ||
marcel@hsdev.com | 2003-02-27 | Insert the relation diagram in here? |
9 The naming convention says that the event name starts with the core package name that registers it (the owner), beginning with a capital letter. The specific name then follows directly, also beginning with a capital letter. No spaces or special characters are allowed. Example:
xarEvt_registerEvent('ServerRequest');
10 At certain points in the system load process the registered events can be triggered by calling the function
xarEvt_trigger($eventName, $value)with $value being an optional variable that can be passed to the event handlers. Example:
xarEvt_trigger('ServerRequest');
11 This function always returns. It might be the case that event handlers do not exist or that event handlers do something funny. The system relies on the exception handling system to catch these situations. The xarEvt_Trigger function neither sets directly exceptions nor handles them from its callees.
12 Each module, in turn, can implement an event handler function, that will be executed as soon as the corresponding event is being triggered by the core. The function must be situated in the file xareventapi.php of the module and must adhere the following naming convention:
function {$modName}_eventapi_On$EventName($arg) { // event handler code, e.g. db interaction, ... }Example:
function sniffer_eventapi_OnSessionCreate($arg) { // browsersniffing }
13
I eventlist (type: missing, status: open) | ||
marcel@hsdev.com | 2003-02-27 | Can we include a list of supported events. Better still, a list of events we want with a marker which ones are supported / implemented and which ones are not |
14 2002-02-27 : Version 0.2
15 2003-02-26 : Version 0.1
16 2003-02-23 : Created