4.2.4. Events

⁠4.2.4. Events

Plugins have an integrated method for both declaring and hooking events, without needing to directly call the event API functions. These take the form of class methods on your plugin.

To declare a new event, or a set of events that your plugin will trigger, override the events() method of your plugin class, and return an associative array with event names as the key, and the event type as the value.

Let's add to our Example plugin, a new event foo that does not expect a return value (an "execute" event type), and another event bar expecting a single value that gets modified by each hooked function (a "chain" event type):

Example/Example.php

<?php
class ExamplePlugin extends MantisPlugin {
    ...

    function events() {
        return array(
            'EVENT_EXAMPLE_FOO' => EVENT_TYPE_EXECUTE,
            'EVENT_EXAMPLE_BAR' => EVENT_TYPE_CHAIN,
        );
    }
}

When the Example plugin is loaded, the event system in MantisBT will add these two items to its list of events, and will then allow other plugins or functions to hook them.

Note

Naming the events "EVENT_PLUGINBASENAME_EVENTNAME" is not required, but is considered best practice to avoid conflicts between plugins.

Hooking events, whether they are your own plugin's or defined elsewhere, is almost identical to declaring them. Instead of passing an event type as the value, your plugin must give the name of a class method that will be called when the event is triggered.

For our Example plugin, we'll create a foo() and a bar() methods in our plugin class, then hook them to the events we declared earlier. We'll also hook the standard EVENT_MENU_MAIN event, to link the custom page we created in Section 4.2.3, “Pages and Files”.

Example/Example.php

<?php
class ExamplePlugin extends MantisPlugin {
    ...

    function hooks() {
        return array(
            'EVENT_MENU_MAIN' => 'menu',

            'EVENT_EXAMPLE_FOO' => 'foo',
            'EVENT_EXAMPLE_BAR' => 'bar',
        );
    }
}

Function signatures vary depending on the hooked event's type (see Section 3.3, “Event Types”). They generally should accept the $p_event parameter, which contains the event name triggering the method (allowing a single method to respond to multiple events). The bar() method also accepts and returns a second parameter, in order to match the expectations of chained events.

Now that we have our plugin's events declared and hooked, let's define the hook methods and modify our earlier page so it triggers the new events:

Example/Example.php

<?php
class ExamplePlugin extends MantisPlugin {
    ...
    function menu() {
        $t_menu[] = array(
            'title' => $this->name,
            'url' => plugin_page( 'foo' ),
            'access_level' => ANYBODY,
            'icon' => 'fa-smile-o'
        );
        return $t_menu;
    }

    function foo( $p_event ) {
        echo 'In method foo(). ';
    }

    function bar( $p_event, $p_chained_param ) {
        return str_replace( 'foo', 'bar', $p_chained_param );
    }
}

Example/pages/foo.php
...

<p>
    Custom event hooks:
<?php
event_signal( 'EVENT_EXAMPLE_FOO' );

$t_string = 'A sentence with the word "foo" in it.';
$t_new_string = event_signal( 'EVENT_EXAMPLE_BAR', array( $t_string ) );
echo $t_new_string;
?>
</p>

When the first event "foo" is signaled, the Example plugin's foo() method will execute and echo a string. After that, the second event "bar" is signaled, and the page passes a string parameter; the plugin's bar() gets the string and replaces any instance of "foo" with "bar", and returns the resulting string. If any other plugin had hooked the event, that plugin could have further modified the new string from the Example plugin, or vice versa, depending on the loading order of plugins. The page then echos the modified string that was returned from the event.