This post originated from an RSS feed registered with PHP Buzz by Forum One. Original Post: How Do Events & Notifications Work? Feed Title: Syntax Framework Feed URL: http://blog.syntaxcms.org/rss.php?version=0.91 Feed Description: Finally, a place to answer Syntax questions Latest PHP Buzz Posts Latest PHP Buzz Posts by Forum One Latest Posts From Syntax Framework

The architecture is quite simple. There are two new classes:

• pxdb_event_dispatcher (lib/ext/PxDB/classes/events/pxdb_event_dispatcher.class.php)
• pxdb_event_listener (lib/ext/PxDB/classes/events/pxdb_event_listener.class.php)

A pxdb_event_dispatcher object is created in pxdb.inc.php. It is a singleton object so if you try and create a new object it will only return a reference to this single instance of the dispatcher. When this object is created it looks in the directory lib/ext/PxDB/events for event listeners.

Event listeners are classes that implement (extend) the pxdb_event_listener abstract class. In order to be automatically registered as listeners they must:

• Be located in the lib/ext/PxDB/events directory
• The file must have the file extension .class.php
• The class must be a subclass of pxdb_event_listener
• The class must add triggers to indicate what triggers/events it is interested in receiving
• The class must define and implement a method called execute(). This is the method that will be called by the dispatcher when an event occurs

When a listener is registered any notifications sent to the dispatcher will be sent to the listener if that listener has expressed an interest in receiving the notification. If the listener has expressed an interest in receiving the notification then the dispatcher will call the listener's execute() method where all the actual work of the listener is executed.

NOTE: The event dispatcher will loop through all the registered listeners that have been mapped to that trigger/event. Listeners can be chained in such a way that multiple listeners can handle the same event. Common sense and good application design is expected from developers.

The event/triggers that have been defined and implemented in the pxdb_commit class include:

• SYNTAX_EVENT_INSERT : An new content-item is added to the database
• SYNTAX_EVENT_UPDATE : An existing content-item is modified
• SYNTAX_EVENT_DELETE : A content-item is removed from the database
• SYNTAX_EVENT_APPROVE : A content-item is approved
• SYNTAX_EVENT_UNAPPROVE : A content-item is unapproved
• SYNTAX_EVENT_PUBLISH : A content-item is published to a section
• SYNTAX_EVENT_UNPUBLISH : A content-item is removed from a section

Important Caveats

• Since events are triggered when an object is saved (INSERT, UPDATE), removed (DELETE) or approved (APPROVED, UNAPPROVE) an event listener should not perform any operation on the triggered object that will fire one of these events. There is a very real danger of creating an infinite loop condition by doing so.
• You will also want to be very careful about changing the record state because of how events chain. The order in which event listeners are called is determined from the filename order in the directory. There is a danger that you get the order wrong and your data gets changed into an inconsistant state that is difficult to debug when problems and side-effects arise. If you need to change the state of an object consider using a post-processor plugin before resorting to using event listeners.

I will post detailed instructions on how to write your own event listener classes with some examples in a follow-up article.