System Event Hooks

The eleven hooks over the installation itself: add-ons, announcements, imports, tasks, versions, upgrades, the site map and certificates.

Overview

These hooks watch the installation itself rather than a customer: which add-on was installed, which announcement went out, which transfer finished, whether a new version appeared or was installed.

Three of them face outward: the site map towards search engines, the certificate sweep towards your alerting, and the transfer page towards the parties looking at it.

Reference

Following an add-on being installed

Runs after an add-on package is installed. Being installed does not mean it is switched on.

Hook::add('action:addon.installed', 10, function ($module, $activated) {
    // Installed does not mean switched on.
    if ($activated) Acme::onEnabled($module);
});

Following an add-on status change

Runs when an add-on is switched on or off.

Hook::add('action:addon.status_changed', 10, function ($key, $status) {
    if ($status === 'disable') Acme::pauseIntegration($key);
});

Following an add-on being deleted

Runs after an add-on is removed.

Hook::add('action:addon.deleted', 10, function ($module) {
    Acme::cleanupIntegration($module);
});

Following an announcement being saved

Runs after an announcement is saved.

Hook::add('action:announcement.saved', 10, function ($savedId, $data, $isNew) {
    // Carry only a new announcement to the outside channel.
    if ($isNew) Acme::broadcast($data['title'] ?? '', $data['message'] ?? '');
});

Following an import finishing

Runs when a transfer from another system finishes. It fires per data type: customers, products and invoices each finish separately.

Hook::add('action:import.completed', 10, function ($platform, $type, $result) {
    // It fires per type: this does not mean "everything is done".
    Acme::noteImport($platform, $type, $result);
});

Following a task being saved

Runs when a task inside the panel is saved.

Hook::add('action:task.saved', 10, function ($id, $is_new) {
    if ($is_new) Acme::mirrorTask($id);
});

Following a new version being spotted

Runs when a new core version is spotted. Nothing is upgraded: this is only news.

Hook::add('action:updates.new_version_detected', 10, function ($response, $current_version) {
    // Nothing is upgraded here, it is only reported.
    Acme::notifyOps('new version: ' . ($response['version'] ?? '?'));
});

Following a core upgrade

Runs once after the installed version changes, on the first cron run that loads the new code. It is the moment to install what the upgrade brought: an enabled module gets no other call. Available from 5.0-beta.4.

Hook::add('action:core.updated', 10, function ($update = []) {
    // Once per version change; files that already exist are kept.
    Acme::installMissingTemplates($update['version'] ?? '');
});

Adding addresses to the site map

Runs while the site map is produced. Announce your own pages to search engines here.

Hook::add('filter:sitemap.links', 10, function (&$links, &$ctx) {
    // The hook runs once per language.
    foreach (Acme::publicPages($ctx['lang'] ?? '') as $url) $links[] = $url;
});

Reporting certificates about to expire

Runs while certificates nearing their end are collected. Add certificates the core does not know about here.

Hook::add('filter:ssl.expiring_services', 10, function ($maxDays) {
    // Return only YOUR share: the core merges them all.
    return Acme::expiringCerts($maxDays);
});

Enriching the transfer verification page

Runs while the licence transfer verification page is shown. Add information of your own here.

Hook::add('filter:license.transfer.verify_context', 10, function (&$ctx) {
    $ctx['acme_note'] = Acme::transferNote((int) ($ctx['transfer']['id'] ?? 0));
});

Pitfalls

Related Articles

• How Hooks Work
• Hook Domains
• Writing a Hook Listener