Events introduction

Events in Vvveb CMS provide extension points where data can be modified or additional actions can be performed.

They are the primary mechanism that plugins use to extend or customize Vvveb’s behavior without altering core code.

All event handling is managed through the Vvveb\System\Event class.

Registering Events

To run custom code when an event occurs, use the Event::on() method:

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

Parameters

• $namespace — Usually the full namespace and class where the event originates.
• $name — Typically the method name where the event is triggered. If multiple events exist in the same method, this can be a custom identifier.
• $id — A unique identifier for the callback, often the class name (__CLASS__) registering the event.
• $callback — The function executed when the event is triggered.
• $priority — Determines execution order when multiple callbacks are registered. Lower numbers run first.

Examples

Add an item to the admin dashboard menu

// 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];
});

Modify post component results

//__CLASS__ is usually used instead of  Vvveb\Plugins\ContentPlugin' for better code maintenance.
Event::on('Vvveb\Component\Post', 'results', __CLASS__, function ($results = false) {
	if ($results) {
		$results['content'] .= 'This is added at the end of all posts';
	}
	return [$results];
});

Add Gravatar images to comments

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

Triggering Events

To allow plugins to modify data or perform actions, trigger an event using:

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

Parameters

• $namespace — Full namespace and class where the event is triggered.
• $name — Method name or custom event identifier.
• $parameters — One or more values passed to event callbacks.

Examples

Triggering inside a component’s results() method

list($results) = Event::trigger(__CLASS__, __FUNCTION__, $results);

Triggering with multiple parameters

list($content, $language, $slug) = Event::trigger(__CLASS__, __FUNCTION__, $content, $language, $slug);

The returned values replace the originals, allowing plugins to modify them.

Removing Events

To remove previously registered events, use:

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

Usage

• Remove a specific callback by its ID.
• Remove all callbacks for a specific event.
• Remove all callbacks for an entire namespace.

Examples

// Remove a specific plugin callback
Event::off('Vvveb\Component\Post', 'results', 'Vvveb\Plugins\ContentPlugin');

// Remove all callbacks for the "results" event
Event::off('Vvveb\Component\Post', 'results');

// Remove all events in the Post component namespace
Event::off('Vvveb\Component\Post');

Inspecting Registered Events

To list registered events, use:

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

Examples

// All callbacks for Post component "results" event
$events = Event::getEvents('Vvveb\Component\Post', 'results');

// All events in the Post component namespace
$events = Event::getEvents('Vvveb\Component\Post');

// All registered events in the system
$events = Event::getEvents();

The event system is one of the most powerful extension mechanisms in Vvveb CMS, enabling plugins to modify data, extend functionality, and integrate seamlessly with core components.