5.1. Events

• 5.1.1. Basics
• 5.1.2. Advanced
• 5.1.3. API (4)

In Cradle, routes and middleware are all types of events. If your new to events, they have two typical parts, which are to listen and to fire.

5.1.1. Basics

A typical listen semantically looks like the following.

cradle()->on('Some Event', function(...$args) {
    //Do something here
});

In the example above there are two main arguments. The first one expressed as 'Some Event' is called the event. The second argument expressed as a function is called a handler. To fire off 'Some Event' in the example above, we can use the follow example below.

cradle()->trigger('Some Event', ...$args);

As you noticed with ->trigger() you can pass an N amount of arguments to the event handler. To prevent writing all the event handlers in one file you can optionally include the event handler in another file.

cradle()->on('Some Event', include('/some/event/handler.php'));

With this set, you can create a file located where you specified the event handler and return a function like the following example below.

/some/event/handler.php

return function(...$args) {
    //Do something here
};

This isn't doing any Cradle magic. It's just how PHP works.

$this

Event handlers also have a populated $this variable which is the same as cradle(). This means you can also fire events within your event handler. The following shows how this can be done.

cradle()->on('Some Event', function(...$args) {
    //Do something here
    $this->trigger('Another Event');
});

The simplicity of the event interface in Cradle is by design, and used constantly throughout the framework, some of which require more advance features from events. Though in most cases you may not have a need for the following features in the next section, describes such needs of the framework which you can also use at your convenience.

5.1.2. Advanced

sprintf()

Cradle events differ than most event dispatchers because it opens up the listener API for you to use, but be careful of it’s over usage, because it may impact performance (which is why most close off this). The first listener interface resembles a sprintf() type string.

Listening via sprintf()

cradle()
    ->on('Some %s Event', function(...$args) {
        //output the first variable
        echo $this->getEventHandler()->getMeta()['variables'][0]; //--> Random
    })
    ->trigger('Some Random Event');

Given the example above, we use '%s' to denote that we are expecting a variable. As long as the event being fired off matches 'Some %s Event' the relative event handler will be called. For example, cradle()->trigger('Some Good Event') will match the case above.

Meta Data

To get the variable we call on the event handler using $this->getEventHandler()->getMeta() which returns meta data about the current event. The meta data is an array that contains information like 'event', 'pattern', 'callback' you can use to help process an event.

There isn't an easy way to access meta data inside the event handler because
you would only need to know about meta data in advance cases.

Meta data is short lived. It updates every time there is a new event. At the end of an event trigger, the meta data will hold one of three statuses.

• EventHandler::STATUS_OK (200) - All event listeners were triggered
• EventHandler::STATUS_INCOMPLETE (308) - The last event triggered returned false
• EventHandler::STATUS_NOT_FOUND (404) - No event listeners were triggered because none were defined

Regular Expressions

It is also possible to listen to events via regular expressions. Cradle will case for strings to be evaluated as a regular expression if the event starts with a # and has a # in the end like the following example below.

Listening via Regular Expressions

cradle()
    ->on('#Some\s(.+)\sEvent#', function(...$args) {
        //output the first variable
        echo $this->getEventHandler()->getMeta()['variables'][0]; //--> Random
    })
    ->trigger('Some Random Event');

It is also possible to use expression modifiers like `#Some\s(.+)\sEvent#is`
in the end.

Make sure you know how to Regex. Invalid regular expressions will throw out an
error or make the variables results unexpected.

Using too much regular expressions will slow down your application.

5.1.3. API

on - Attaches an instance to be notified when an event has been triggered

cradle()->on('Some Event', function(...$args) {
    //Do something here
});

trigger - Notify all observers of that a specific event has happened

cradle()->trigger('Some Event', ...$args);

setEventHandler - Allows for a custom event dispatcher to be used

cradle()->setEventHandler(new Cradle\Event\EventHandler, false);

getEventHandler - Returns an EventHandler object if none was set, it will auto create one

cradle()->getEventHandler();