In Theia, an "event" is when a certain action or circumstance has occurred, and each event is "announced" by sending a signal, along with some relevant data.
The idea behind the signal and event system within Theia is simple:
Sometimes lots of memory intensive routines and functions need to be invoked that would normally cause a major performance hit as they are processed (for example sending a hundred or so email notifications). And sometimes, there are also situations in which the urgency of what needs to be done can simply be briefly put on hold (for example, an award being rewarded, some might argue, doesn't necessarily need to happen right away). These are scenarios in which the signal and event system come in handy.
Events are first announced, and then later on (typically using cron) are listened to (processed).
Complete list of signals
For a complete list of signals, go here!
Announcing an event
An event is announced by invoking the "Announce" method of the class, "Event". As there is not always an existing Event object, it's best to call it like so:
PHP CODE
Event::Announce();
Event::Announce accepts two arguments:
- the signal, which is a positive integer representing the action that is being announced
- an array of name / value pairs (this data gets saved with the event announcement, and is referred to later when listened to recall information about the event
Here is what an example call might look like (with the signal and array):
PHP CODE
Event::Announce(3, array("id"=>$id, "user"=>$user));
In this example, the "new item" event is being announced (signal 3), and its ID and creator would be saved along with the event. Typically, more data pairs will be present in the second argument's array, but for the purpose of this tutorial, we'll pretend only two bits of data are being saved.
The reason extra data is sent with the event's announcement is because, later on, when the event is listened to, certain information needs to be present to properly treat the event.
For example, when an item is created, it would seem obvious to save its ID since this would no doubt come up when the event is being processed. The same goes for the user who created the item; since maybe a notification will get sent, it's important to know who not to send the notification to.
Listening to events
Events are listened to by the cron daemon, by executing the following script:
DIR_LIB/cron/listen.cron.php
You can also listen to events by calling Event::Listen(). This method accepts two arguments, both of which are optional.
The first argument is used for when you want to specify a signal of events you want to listen for. Suppose you only wanted to listen to "new item" (signal 3) events. If you do not provide the first argument, which is for the signal (a positive integer), then any events will be listened to.
The second argument is is also an integer, but is used to state how many events should be listened for. Because listening to and processing events can be a dramatic memory hog, this argument is set at 10, by default. Listening to a hundred or so events every minute shouldn't cause a significant decrease in performance, but you need to specify if more than 10 events should be listened to at a time.Here is an example call, which asks to listen to only the first 50 new item events (if any exist):
PHP CODE
Event::Listen(3, 50);
And here is an example where we are listening to any type of events, but only the first hundred of them (should any exist):
Event::Listen(null, 100);
The first argument, signal, can be set as null or 0 if you want it to listen to any events.
How events are processed
When an event is processed, the first thing that is done is the data that was sent with the announcement is restored back into a workable array ($d). Earlier, in the example of announcing the new item event, I used two pairs in the array of data (id and user). This would mean, I could refer to these values in the event files by using the variables:
- $d['id']
- $d['user']
What are "event files" and how to add your own
Event files are PHP scripts that are automatically run whenever a certain signal is sent. All event files reside in DIR_EVT (this directory is set at lib/event by default, but can be changed for security purposes). The files must start with the signal ID, and can optionally be appended with a hyphen, underscore or period, separating some flag used to help remind you of what the file is for.
You already have several event files in DIR_EVT, as many are built into Theia. If you take a look inside DIR_EVT, you will see many files named with a number and ending with a ".php" extension.Throughout this page we've been referring to the "new item" signal (3), so let's assume here that we want to add our own routines or code that gets processed each time a new item event occurs. While you could just as well add the code to DIR_EVT/3.php, this is discouraged as for dealing with support, we need to be sure that your code isn't causing the problem.
But there is a perfect solution here; create a new file called 3_myeventdata.php instead. You can dileniate the signal from the comment / name data by using either a hyphen, underscore or period. So you could also make another file called 3.awards.php. In fact, you can have as many signal files for the same signal as you want, and each of them will get run each and every time an event with that signal occurs.
Things to consider
Although an event may have been listened to, if it was invoking MailQ::Send, it does not necessarily mean that any associated emails or notifications have been sent already (it just means they have been added to the queue). Because of the nature of the MailQ system, there may be a lag between when the event was listened to and when the email / notification it sends gets sent.
Consider this scenario... You have a cronjob setup to listen to events every single minute, but you also have a cronjob setup to send a batch of emails through the MailQ. Depending on how many emails are waiting to be delivered on queue, the time from when the event was announced until the time the email gets sent can be anywhere from six minutes and up (one minute maximum until the event is listened to, and five minutes maximum from then until the MailQ process is invoked).
And again, if you only have MailQ setup to send 500 emails at a time, and you have 2000 emails waiting to be sent, then the total time from when the event is announced until the time the email is sent, would be 21 minutes here (assuming events are listened to every minute and MailQ works every five minutes).
So, if for some reason, you are wondering why you haven't received an email that you know the event has been listened to for, then try checking out the admin tool (in the "email management" section), "manage unsent emails on queue" (admin tool 152). If it's on queue, then the event has been processed fine, and MailQ is just waiting to deliver the message.
