Events introduction

Registering events

Events in Vvveb are points in the code where data can be modified or an action can be performed.

It's the main method that plugins can use to extend Vvveb functionality.

Vvveb\System\Event class is used for all event handling.

You can run code when an event is triggered using the Event::on method which has the following definition:

function on($namespace, $name, $id, $callback, $priority = 1000) 

• $namespace is usually the complete namespace and class from where the event is triggered.
• $name is usually the method name of the class where the event is triggered but it can also be a unique identifier if there are more events triggered in the method.
• $callback is the function that will be run when the event is triggered
• $id is a unique identifier used to identify the code that attached to the event, it is usually the method or class from where the Event::on is called for easier identification.
• $priority the order in which the callbacks will called.

it can be used like in the the following example:

// add a new entry in the admin dashboard menu, used by plugins to add a link to plugin settings
Event::on('Vvveb\Controller\Base', 'init-menu', __CLASS__, function ($menu) use ($admin_path) {
    $menu['plugins']['items']['insert-scripts'] = [
        'name'     => __('Insert scripts'),
        'url'      => $admin_path . '?module=plugins/insert-scripts/settings',
        'icon-img' => PUBLIC_PATH . 'plugins/insert-scripts/insert-scripts.svg',
    ];

    return [$menu];
});

// filter post component data and add a text at the end of the post, __CLASS__ is usually used instead of  Vvveb\Plugins\ContentPlugin' for better code maintenance.
// namespace is the component class and results the method
Event::on('Vvveb\Component\Post', 'results', 'Vvveb\Plugins\ContentPlugin', function ($results = false) {
    if ($results) {

        $results['content']  .= 'This is added at the end of all posts';
    }

    return [$results];
});

// filter comments and add gravatars for users that don't have an avatar,  __CLASS__ is usually used instead of 'Vvveb\Plugins\GravatarPlugin' for convenience.
Event::on('Vvveb\Component\Comments', 'results', 'Vvveb\Plugins\GravatarPlugin' , function ($comments) {
    foreach ($comments['comments'] as &$comment) {
        $comment['avatar'] = 'https://www.gravatar.com/avatar/' . md5(strtolower($comment['email']));
    }

    return [$comments];
});

Triggering events

To trigger events where plugins can register and filter data or perfom actions you need to use Event :: trigger method.

function trigger($namespace, $name, $paramters)

• $namespace is usually the complete namespace and class from where the event is triggered.
• $name is usually the method name of the class where the event is triggered but it can also be a unique identifier if there are more events triggered in the method.
• $parameters data that will be changed, it can be any number of parameters.

To allow plugins to change data in some part of your code you can pass the parameter to trigger and use the returned data.

// Event trigger used by results method in components classes, all components trigger this event.
list($results) = Event :: trigger(__CLASS__,__FUNCTION__, $results);

// Event trigger used in the post module to allow plugins to either change content, language and slug or peform other actions using the data
list($content, $language, $slug) = Event :: trigger(__CLASS__,__FUNCTION__, $content, $language, $slug);

Removing events

To remove events registered by a certain plugin you need to use the Event :: off method and pass the unique idenfifier which is usually the class name.

You can also remove all events by passing only namespace and name or only namespace to remove all events in the namespace.

Method definition:

function off($namespace, $name = false, $eventId = false) {

Examples:

// remove ContentPlugin callback that changes Post component results data
Event::off('Vvveb\Component\Post', 'results', 'Vvveb\Plugins\ContentPlugin');

// remove all events that changes Post component results data
Event::off('Vvveb\Component\Post', 'results');

// remove all events from Post component
Event::off('Vvveb\Component\Post'); 

Get event list

Get all events registered either for specific event, for all events in a namespace or all registered events

Method definition:

function getEvents($namespace = false, $name = false)

Examples:

// all events that process post component results data
$events = Event:getEvents('Vvveb\Component\Post', 'results')

// all events that process post component data
$events = Event:getEvents('Vvveb\Component\Post')

// all registered events
$events = Event:getEvents()