Events

This is a complete list of available hooks.

Access

Access.createAccessSingleton

Defined in Piwik/Access in line 46

Callback Signature:

function(&self::$instance)

API

API.$pluginName.$methodName

Defined in Piwik/API/Proxy in line 206

Triggered before an API request is dispatched. This event exists for convenience and is triggered directly after the API.Request.dispatch event is triggered. It can be used to modify the arguments passed to a single API method.

Note: This is can be accomplished with the API.Request.dispatch event as well, however event handlers for that event will have to do more work.

Example

Piwik::addAction('API.Actions.getPageUrls', function (&$parameters) {
    // force use of a single website. for some reason.
    $parameters['idSite'] = 1;
});

Callback Signature:

function(&$finalParameters)

API.$pluginName.$methodName.end

Defined in Piwik/API/Proxy in line 256

Triggered directly after an API request is dispatched. This event exists for convenience and is triggered immediately before the API.Request.dispatch.end event. It can be used to modify the output of a single API method.

Note: This can be accomplished with the API.Request.dispatch.end event as well, however event handlers for that event will have to do more work.

Example

// append (0 hits) to the end of row labels whose row has 0 hits
Piwik::addAction('API.Actions.getPageUrls', function (&$returnValue, $info)) {
    $returnValue->filter('ColumnCallbackReplace', 'label', function ($label, $hits) {
        if ($hits === 0) {
            return $label . " (0 hits)";
        } else {
            return $label;
        }
    }, null, array('nb_hits'));
}

Callback Signature:

$endHookParams

API.getReportMetadata.end

Defined in Piwik/Plugins/API/ProcessedReport in line 259

Triggered after all available reports are collected. This event can be used to modify the report metadata of reports in other plugins. You could, for example, add custom metrics to every report or remove reports from the list of available reports.

Callback Signature:

function(&$availableReports, $parameters)

Usages:

Goals::getReportMetadataEnd

API.getSegmentDimensionMetadata

Defined in Piwik/Plugins/API/API in line 150

Triggered when gathering all available segment dimensions. This event can be used to make new segment dimensions available.

Example

public function getSegmentsMetadata(&$segments, $idSites)
{
    $segments[] = array(
        'type'           => 'dimension',
        'category'       => Piwik::translate('General_Visit'),
        'name'           => 'General_VisitorIP',
        'segment'        => 'visitIp',
        'acceptedValues' => '13.54.122.1, etc.',
        'sqlSegment'     => 'log_visit.location_ip',
        'sqlFilter'      => array('Piwik\IP', 'P2N'),
        'permission'     => $isAuthenticatedWithViewAccess,
    );
}

Callback Signature:

function(&$segments, $idSites)

Usages:

CustomVariables::getSegmentsMetadata

API.Request.authenticate

Defined in Piwik/API/Request in line 257

Triggered when authenticating an API request, but only if the token_auth query parameter is found in the request. Plugins that provide authentication capabilities should subscribe to this event and make sure the global authentication object (the object returned by Registry::get('auth')) is setup to use $token_auth when its authenticate() method is executed.

Callback Signature:

function($token_auth)

Usages:

Login::ApiRequestAuthenticate

API.Request.dispatch

Defined in Piwik/API/Proxy in line 186

Triggered before an API request is dispatched. This event can be used to modify the arguments passed to one or more API methods.

Example

Piwik::addAction('API.Request.dispatch', function (&$parameters, $pluginName, $methodName) {
    if ($pluginName == 'Actions') {
        if ($methodName == 'getPageUrls') {
            // ... do something ...
        } else {
            // ... do something else ...
        }
    }
});

Callback Signature:

function(&$finalParameters, $pluginName, $methodName)

API.Request.dispatch.end

Defined in Piwik/API/Proxy in line 296

Triggered directly after an API request is dispatched. This event can be used to modify the output of any API method.

Example

// append (0 hits) to the end of row labels whose row has 0 hits for any report that has the 'nb_hits' metric
Piwik::addAction('API.Actions.getPageUrls', function (&$returnValue, $info)) {
    // don't process non-DataTable reports and reports that don't have the nb_hits column
    if (!($returnValue instanceof DataTableInterface)
        || in_array('nb_hits', $returnValue->getColumns())
    ) {
        return;
    }

    $returnValue->filter('ColumnCallbackReplace', 'label', function ($label, $hits) {
        if ($hits === 0) {
            return $label . " (0 hits)";
        } else {
            return $label;
        }
    }, null, array('nb_hits'));
}

Callback Signature:

$endHookParams

ArchiveProcessor

ArchiveProcessor.Parameters.getIdSites

Defined in Piwik/ArchiveProcessor/Parameters in line 110

Callback Signature:

function(&$idSites, $this->getPeriod())

AssetManager

AssetManager.filterMergedJavaScripts

Defined in Piwik/AssetManager/UIAssetMerger/JScriptUIAssetMerger in line 71

Triggered after all the JavaScript files Piwik uses are minified and merged into a single file, but before the merged JavaScript is written to disk. Plugins can use this event to modify merged JavaScript or do something else with it.

Callback Signature:

function(&$mergedContent)

AssetManager.filterMergedStylesheets

Defined in Piwik/AssetManager/UIAssetMerger/StylesheetUIAssetMerger in line 74

Triggered after all less stylesheets are compiled to CSS, minified and merged into one file, but before the generated CSS is written to disk. This event can be used to modify merged CSS.

Callback Signature:

function(&$mergedContent)

AssetManager.getJavaScriptFiles

Defined in Piwik/AssetManager/UIAssetFetcher/JScriptUIAssetFetcher in line 47

Triggered when gathering the list of all JavaScript files needed by Piwik and its plugins. Plugins that have their own JavaScript should use this event to make those files load in the browser.

JavaScript files should be placed within a javascripts subdirectory in your plugin's root directory.

Note: While you are developing your plugin you should enable the config setting [Development] disable_merged_assets so JavaScript files will be reloaded immediately after every change.

Example

public function getJsFiles(&$jsFiles)
{
    $jsFiles[] = "plugins/MyPlugin/javascripts/myfile.js";
    $jsFiles[] = "plugins/MyPlugin/javascripts/anotherone.js";
}

Callback Signature:

function(&$this->fileLocations)

Usages:

Actions::getJsFiles, Annotations::getJsFiles, CoreAdminHome::getJsFiles, CoreHome::getJsFiles, CorePluginsAdmin::getJsFiles, CoreVisualizations::getJsFiles, Dashboard::getJsFiles, ExamplePlugin::getJsFiles, Feedback::getJsFiles, Goals::getJsFiles, Insights::getJsFiles, LanguagesManager::getJsFiles, Live::getJsFiles, Login::getJsFiles, MobileMessaging::getJsFiles, MultiSites::getJsFiles, Overlay::getJsFiles, PrivacyManager::getJsFiles, ScheduledReports::getJsFiles, SegmentEditor::getJsFiles, SitesManager::getJsFiles, Transitions::getJsFiles, UserCountry::getJsFiles, UserCountryMap::getJsFiles, UsersManager::getJsFiles, Widgetize::getJsFiles, ZenMode::getJsFiles

AssetManager.getStylesheetFiles

Defined in Piwik/AssetManager/UIAssetFetcher/StylesheetUIAssetFetcher in line 67

Triggered when gathering the list of all stylesheets (CSS and LESS) needed by Piwik and its plugins. Plugins that have stylesheets should use this event to make those stylesheets load.

Stylesheets should be placed within a stylesheets subdirectory in your plugin's root directory.

Example

public function getStylesheetFiles(&$stylesheets)
{
    $stylesheets[] = "plugins/MyPlugin/stylesheets/myfile.less";
    $stylesheets[] = "plugins/MyPlugin/stylesheets/myotherfile.css";
}

Callback Signature:

function(&$this->fileLocations)

Usages:

Plugin::getStylesheetFiles, Actions::getStylesheetFiles, Annotations::getStylesheetFiles, CoreAdminHome::getStylesheetFiles, CoreHome::getStylesheetFiles, CorePluginsAdmin::getStylesheetFiles, CoreVisualizations::getStylesheetFiles, DBStats::getStylesheetFiles, Dashboard::getStylesheetFiles, ExampleRssWidget::getStylesheetFiles, Feedback::getStylesheetFiles, Goals::getStylesheetFiles, Insights::getStylesheetFiles, Installation::getStylesheetFiles, LanguagesManager::getStylesheetFiles, Live::getStylesheetFiles, MobileMessaging::getStylesheetFiles, MultiSites::getStylesheetFiles, SegmentEditor::getStylesheetFiles, SitesManager::getStylesheetFiles, Transitions::getStylesheetFiles, UserCountry::getStylesheetFiles, UserCountryMap::getStylesheetFiles, UsersManager::getStylesheetFiles, VisitsSummary::getStylesheetFiles, Widgetize::getStylesheetFiles, ZenMode::getStylesheetFiles

Config

Config.badConfigurationFile

Defined in Piwik/FrontController in line 372

Triggered when Piwik cannot access database data. This event can be used to start the installation process or to display a custom error message.

Callback Signature:

function($exception)

Usages:

Installation::dispatch

Config.NoConfigurationFile

Defined in Piwik/FrontController in line 276

Triggered when the configuration file cannot be found or read, which usually means Piwik is not installed yet. This event can be used to start the installation process or to display a custom error message.

Callback Signature:

function($exception)

Usages:

Installation::dispatch

Console

Console.filterCommands

Defined in Piwik/Console in line 94

Triggered to filter / restrict console commands. Plugins that want to restrict commands should subscribe to this event and remove commands from the existing list.

Example

public function filterConsoleCommands(&$commands)
{
    $key = array_search('Piwik\Plugins\MyPlugin\Commands\MyCommand', $commands);
    if (false !== $key) {
        unset($commands[$key]);
    }
}

Callback Signature:

function(&$commands)

Controller

Controller.$module.$action

Defined in Piwik/FrontController in line 574

Triggered directly before controller actions are dispatched. This event exists for convenience and is triggered directly after the Request.dispatch event is triggered.

It can be used to do the same things as the Request.dispatch event, but for one controller action only. Using this event will result in a little less code than Request.dispatch.

Callback Signature:

function(&$parameters)

Controller.$module.$action.end

Defined in Piwik/FrontController in line 591

Triggered after a controller action is successfully called. This event exists for convenience and is triggered immediately before the Request.dispatch.end event is triggered.

It can be used to do the same things as the Request.dispatch.end event, but for one controller action only. Using this event will result in a little less code than Request.dispatch.end.

Callback Signature:

function(&$result, $parameters)

CronArchive

CronArchive.archiveSingleSite.finish

Defined in Piwik/CronArchive in line 335

This event is triggered immediately after the cron archiving process starts archiving data for a single site.

Callback Signature:

function($idSite, $completed)

CronArchive.archiveSingleSite.start

Defined in Piwik/CronArchive in line 325

This event is triggered before the cron archiving process starts archiving data for a single site.

Callback Signature:

function($idSite)

CronArchive.filterWebsiteIds

Defined in Piwik/CronArchive in line 929

Triggered by the core:archive console command so plugins can modify the list of websites that the archiving process will be launched for. Plugins can use this hook to add websites to archive, remove websites to archive, or change the order in which websites will be archived.

Callback Signature:

function(&$websiteIds)

CronArchive.init.finish

Defined in Piwik/CronArchive in line 270

This event is triggered after a CronArchive instance is initialized.

Callback Signature:

function($this->websites->getInitialSiteIds())

Dashboard

Dashboard.changeDefaultDashboardLayout

Defined in Piwik/Plugins/Dashboard/Dashboard in line 101

Allows other plugins to modify the default dashboard layout.

Callback Signature:

function(&$defaultLayout)

Db

Db.cannotConnectToDb

Defined in Piwik/FrontController in line 349

Triggered when Piwik cannot connect to the database. This event can be used to start the installation process or to display a custom error message.

Callback Signature:

function($exception)

Usages:

Installation::displayDbConnectionMessage

Db.getDatabaseConfig

Defined in Piwik/Db in line 82

Triggered before a database connection is established. This event can be used to change the settings used to establish a connection.

Callback Signature:

function(&$dbConfig)

Goals

Goals.getReportsWithGoalMetrics

Defined in Piwik/Plugins/Goals/Goals in line 225

Triggered when gathering all reports that contain Goal metrics. The list of reports will be displayed on the left column of the bottom of every Goals page.

If plugins define reports that contain goal metrics (such as conversions or revenue), they can use this event to make sure their reports can be viewed on Goals pages.

Example

public function getReportsWithGoalMetrics(&$reports)
{
    $reports[] = array(
        'category' => Piwik::translate('MyPlugin_myReportCategory'),
        'name' => Piwik::translate('MyPlugin_myReportDimension'),
        'module' => 'MyPlugin',
        'action' => 'getMyReport'
    );
}

Callback Signature:

function(&$reportsWithGoals)

Usages:

Goals::getActualReportsWithGoalMetrics

Insights

Insights.addReportToOverview

Defined in Piwik/Plugins/Insights/API in line 69

Triggered to gather all reports to be displayed in the "Insight" and "Movers And Shakers" overview reports. Plugins that want to add new reports to the overview should subscribe to this event and add reports to the incoming array. API parameters can be configured as an array optionally.

Example

public function addReportToInsightsOverview(&$reports)
{
    $reports['Actions_getPageUrls']  = array();
    $reports['Actions_getDownloads'] = array('flat' => 1, 'minGrowthPercent' => 60);
}

Callback Signature:

function(&$reports)

Usages:

Actions::addReportToInsightsOverview, Referrers::addReportToInsightsOverview, UserCountry::addReportToInsightsOverview

LanguageManager

LanguageManager.getAvailableLanguages

Defined in Piwik/Plugins/LanguagesManager/API in line 75

Hook called after loading available language files. Use this hook to customise the list of languagesPath available in Piwik.

Callback Signature:

function(&$languages)

Live

Live.API.getIdSitesString

Defined in Piwik/Plugins/Live/API in line 734

Callback Signature:

function(&$idSites)

Live.getExtraVisitorDetails

Defined in Piwik/Plugins/Live/API in line 399

Triggered in the Live.getVisitorProfile API method. Plugins can use this event to discover and add extra data to visitor profiles.

For example, if an email address is found in a custom variable, a plugin could load the gravatar for the email and add it to the visitor profile, causing it to display in the visitor profile popup.

The following visitor profile elements can be set to augment the visitor profile popup:

Callback Signature:

function(&$result)

Live.makeNewVisitorObject

Defined in Piwik/Plugins/Live/VisitorFactory in line 39

Triggered while visit is filtering in live plugin. Subscribers to this event can force the use of a custom visitor object that extends from Piwik\Plugins\Live\VisitorInterface.

Callback Signature:

function(&$visitor, $visitorRawData)

Log

Log.formatDatabaseMessage

Defined in Piwik/Log in line 637

Triggered when trying to log an object to a database table. Plugins can use this event to convert objects to strings before they are logged.

Example

public function formatDatabaseMessage(&$message, $level, $tag, $datetime, $logger) {
    if ($message instanceof MyCustomDebugInfo) {
        $message = $message->formatForDatabase();
    }
}

Callback Signature:

function(&$message, $level, $tag, $datetime, $logger)

Log.formatFileMessage

Defined in Piwik/Log in line 677

Triggered when trying to log an object to a file. Plugins can use this event to convert objects to strings before they are logged.

Example

public function formatFileMessage(&$message, $level, $tag, $datetime, $logger) {
    if ($message instanceof MyCustomDebugInfo) {
        $message = $message->formatForFile();
    }
}

Callback Signature:

function(&$message, $level, $tag, $datetime, $logger)

Log.formatScreenMessage

Defined in Piwik/Log in line 584

Triggered when trying to log an object to the screen. Plugins can use this event to convert objects to strings before they are logged.

The result of this callback can be HTML so no sanitization is done on the result. This means YOU MUST SANITIZE THE MESSAGE YOURSELF if you use this event.

Example

public function formatScreenMessage(&$message, $level, $tag, $datetime, $logger) {
    if ($message instanceof MyCustomDebugInfo) {
        $message = Common::sanitizeInputValue($message->formatForScreen());
    }
}

Callback Signature:

function(&$message, $level, $tag, $datetime, $logger)

Log.getAvailableWriters

Defined in Piwik/Log in line 355

This event is called when the Log instance is created. Plugins can use this event to make new logging writers available.

A logging writer is a callback with the following signature:

function (int $level, string $tag, string $datetime, string $message)

$level is the log level to use, $tag is the log tag used, $datetime is the date time of the logging call and $message is the formatted log message.

Logging writers must be associated by name in the array passed to event handlers. The name specified can be used in Piwik's INI configuration.

Example

public function getAvailableWriters(&$writers) {
    $writers['myloggername'] = function ($level, $tag, $datetime, $message) {
        // ...
    };
}

// 'myloggername' can now be used in the log_writers config option.

Callback Signature:

function(&$writers)

Login

Login.authenticate

Defined in Piwik/Plugins/Login/Auth in line 165

Triggered before authenticate function. This event propagate login and token_auth which will be using in authenticate process.

This event exists to enable possibility for user authentication prevention. For example when user is locked or inactive.

Example

Piwik::addAction('Login.authenticate', function ($login, $tokenAuth) {
    if (!UserActivityManager::isActive ($login, $tokenAuth) {
        throw new Exception('Your account is inactive.');
    }
});

Callback Signature:

function($login, $tokenAuth)

Login.authenticate.successful

Defined in Piwik/Plugins/Login/Auth in line 227

Triggered after successful authenticate, but before cookie creation. This event propagate login and token_auth which was used in authenticate process.

This event exists to enable the ability to custom action before the cookie will be created, but after a successful authentication. For example when user have to fill survey or change password.

Example

Piwik::addAction('Login.authenticate.successful', function ($login, $tokenAuth) {
    // redirect to change password action
});

Callback Signature:

function($login, $tokenAuth)

Login.initSession.end

Defined in Piwik/Plugins/Login/Auth in line 99

Triggered after session initialize. This event notify about end of init session process.

Example

Piwik::addAction('Login.initSession.end', function () {
    // session has been initialized
});

Defined in Piwik/Menu/MenuAdmin in line 134

Callback Signature:

function()

Defined in Piwik/Menu/MenuReporting in line 112

Callback Signature:

function()

Defined in Piwik/Menu/MenuTop in line 101

Callback Signature:

function()

Metrics

Metrics.getDefaultMetricDocumentationTranslations

Defined in Piwik/Metrics in line 379

Use this event to register translations for metrics documentation processed by your plugin.

Callback Signature:

function(&$translations)

Usages:

Actions::addMetricDocumentationTranslations, Events::addMetricDocumentationTranslations

Metrics.getDefaultMetricTranslations

Defined in Piwik/Metrics in line 271

Use this event to register translations for metrics processed by your plugin.

Callback Signature:

function(&$translations)

Usages:

Actions::addMetricTranslations, Events::addMetricTranslations, Goals::addMetricTranslations, MultiSites::addMetricTranslations, UserSettings::addMetricTranslations, VisitFrequency::addMetricTranslations

MobileMessaging

MobileMessaging.deletePhoneNumber

Defined in Piwik/Plugins/MobileMessaging/API in line 221

Triggered after a phone number has been deleted. This event should be used to clean up any data that is related to the now deleted phone number. The ScheduledReports plugin, for example, uses this event to remove the phone number from all reports to make sure no text message will be sent to this phone number.

Example

public function deletePhoneNumber($phoneNumber)
{
    $this->unsubscribePhoneNumberFromScheduledReport($phoneNumber);
}

Callback Signature:

function($phoneNumber)

Usages:

ScheduledReports::deletePhoneNumber

Platform

Platform.initialized

Defined in Piwik/FrontController in line 436

Triggered after the platform is initialized and after the user has been authenticated, but before the platform has handled the request. Piwik uses this event to check for updates to Piwik.

Usages:

CoreUpdater::updateCheck, UsersManager::onPlatformInitialized

Provider

Provider.getCleanHostname

Defined in Piwik/Plugins/Provider/Provider in line 96

Triggered when prettifying a hostname string. This event can be used to customize the way a hostname is displayed in the Providers report.

Example

public function getCleanHostname(&$cleanHostname, $hostname)
{
    if ('fvae.VARG.ceaga.site.co.jp' == $hostname) {
        $cleanHostname = 'site.co.jp';
    }
}

Callback Signature:

function(&$cleanHostname, $hostname)

Referrer

Referrer.addSearchEngineUrls

Defined in Piwik/Common in line 770

Callback Signature:

function(&$searchEngines)

Referrer.addSocialUrls

Defined in Piwik/Common in line 809

Callback Signature:

function(&$socialUrls)

Request

Request.dispatch

Defined in Piwik/FrontController in line 559

Triggered directly before controller actions are dispatched. This event can be used to modify the parameters passed to one or more controller actions and can be used to change the controller action being dispatched to.

Callback Signature:

function(&$module, &$action, &$parameters)

Usages:

Installation::dispatchIfNotInstalledYet

Request.dispatch.end

Defined in Piwik/FrontController in line 601

Triggered after a controller action is successfully called. This event can be used to modify controller action output (if any) before the output is returned.

Callback Signature:

function(&$result, $module, $action, $parameters)

Request.dispatchCoreAndPluginUpdatesScreen

Defined in Piwik/FrontController in line 387

Triggered just after the platform is initialized and plugins are loaded. This event can be used to do early initialization.

Note: At this point the user is not authenticated yet.

Usages:

CoreUpdater::dispatch

Request.initAuthenticationObject

Defined in Piwik/Tracker/Request in line 110

Usages:

Login::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/Plugins/Overlay/API in line 125

Triggered immediately before the user is authenticated. This event can be used by plugins that provide their own authentication mechanism to make that mechanism available. Subscribers should set the 'auth' object in the Piwik\Registry to an object that implements the Piwik\Auth interface.

Example

use Piwik\Registry;

public function initAuthenticationObject($activateCookieAuth)
{
    Registry::set('auth', new LDAPAuth($activateCookieAuth));
}

Callback Signature:

function($activateCookieAuth = true)

Usages:

Login::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/FrontController in line 409

Triggered before the user is authenticated, when the global authentication object should be created. Plugins that provide their own authentication implementation should use this event to set the global authentication object (which must derive from Piwik\Auth).

Example

Piwik::addAction('Request.initAuthenticationObject', function() {
    Piwik\Registry::set('auth', new MyAuthImplementation());
});

Usages:

Login::initAuthenticationObject

ScheduledReports

ScheduledReports.allowMultipleReports

Defined in Piwik/Plugins/ScheduledReports/API in line 776

Triggered when we're determining if a scheduled report transport medium can handle sending multiple Piwik reports in one scheduled report or not. Plugins that provide their own transport mediums should use this event to specify whether their backend can send more than one Piwik report at a time.

Callback Signature:

function(&$allowMultipleReports, $reportType)

Usages:

MobileMessaging::allowMultipleReports, ScheduledReports::allowMultipleReports

ScheduledReports.getRendererInstance

Defined in Piwik/Plugins/ScheduledReports/API in line 425

Triggered when obtaining a renderer instance based on the scheduled report output format. Plugins that provide new scheduled report output formats should use this event to handle their new report formats.

Callback Signature:

function(&$reportRenderer, $reportType, $outputType, $report)

Usages:

MobileMessaging::getRendererInstance, ScheduledReports::getRendererInstance

ScheduledReports.getReportFormats

Defined in Piwik/Plugins/ScheduledReports/API in line 823

Triggered when gathering all available scheduled report formats. Plugins that provide their own scheduled report format should use this event to make their format available.

Callback Signature:

function(&$reportFormats, $reportType)

Usages:

MobileMessaging::getReportFormats, ScheduledReports::getReportFormats

ScheduledReports.getReportMetadata

Defined in Piwik/Plugins/ScheduledReports/API in line 748

TODO: change this event so it returns a list of API methods instead of report metadata arrays. Triggered when gathering the list of Piwik reports that can be used with a certain transport medium.

Plugins that provide their own transport mediums should use this event to list the Piwik reports that their backend supports.

Callback Signature:

function(&$availableReportMetadata, $reportType, $idSite)

Usages:

MobileMessaging::getReportMetadata, ScheduledReports::getReportMetadata

ScheduledReports.getReportParameters

Defined in Piwik/Plugins/ScheduledReports/API in line 602

Triggered when gathering the available parameters for a scheduled report type. Plugins that provide their own scheduled report transport mediums should use this event to list the available report parameters for their transport medium.

Callback Signature:

function(&$availableParameters, $reportType)

Usages:

MobileMessaging::getReportParameters, ScheduledReports::getReportParameters

ScheduledReports.getReportRecipients

Defined in Piwik/Plugins/ScheduledReports/API in line 854

Triggered when getting the list of recipients of a scheduled report. Plugins that provide their own scheduled report transport medium should use this event to extract the list of recipients their backend's specific scheduled report format.

Callback Signature:

function(&$recipients, $report['type'], $report)

Usages:

MobileMessaging::getReportRecipients, ScheduledReports::getReportRecipients

ScheduledReports.getReportTypes

Defined in Piwik/Plugins/ScheduledReports/API in line 799

Triggered when gathering all available transport mediums. Plugins that provide their own transport mediums should use this event to make their medium available.

Callback Signature:

function(&$reportTypes)

Usages:

MobileMessaging::getReportTypes, ScheduledReports::getReportTypes

ScheduledReports.processReports

Defined in Piwik/Plugins/ScheduledReports/API in line 403

Triggered when generating the content of scheduled reports. This event can be used to modify the report data or report metadata of one or more reports in a scheduled report, before the scheduled report is rendered and delivered.

TODO: list data available in $report or make it a new class that can be documented (same for all other events that use a $report)

Callback Signature:

function(&$processedReports, $reportType, $outputType, $report)

Usages:

ScheduledReports::processReports

ScheduledReports.sendReport

Defined in Piwik/Plugins/ScheduledReports/API in line 544

Triggered when sending scheduled reports. Plugins that provide new scheduled report transport mediums should use this event to send the scheduled report.

Callback Signature:

function($report['type'], $report, $contents, $filename, $prettyDate, $reportSubject, $reportTitle, $additionalFiles)

Usages:

MobileMessaging::sendReport, ScheduledReports::sendReport

ScheduledReports.validateReportParameters

Defined in Piwik/Plugins/ScheduledReports/API in line 629

Triggered when validating the parameters for a scheduled report. Plugins that provide their own scheduled reports backend should use this event to validate the custom parameters defined with ScheduledReports::getReportParameters().

Callback Signature:

function(&$parameters, $reportType)

Usages:

MobileMessaging::validateReportParameters, ScheduledReports::validateReportParameters

SegmentEditor

SegmentEditor.deactivate

Defined in Piwik/Plugins/SegmentEditor/API in line 172

Triggered before a segment is deleted or made invisible. This event can be used by plugins to throw an exception or do something else.

Callback Signature:

function($idSegment)

Usages:

ScheduledReports::segmentDeactivation

SegmentEditor.update

Defined in Piwik/Plugins/SegmentEditor/API in line 219

Triggered before a segment is modified. This event can be used by plugins to throw an exception or do something else.

Callback Signature:

function($idSegment, $bind)

Usages:

ScheduledReports::segmentUpdated

Segments

Segments.getKnownSegmentsToArchiveAllSites

Defined in Piwik/SettingsPiwik in line 89

Triggered during the cron archiving process to collect segments that should be pre-processed for all websites. The archiving process will be launched for each of these segments when archiving data.

This event can be used to add segments to be pre-processed. If your plugin depends on data from a specific segment, this event could be used to provide enhanced performance.

Note: If you just want to add a segment that is managed by the user, use the SegmentEditor API.

Example

Piwik::addAction('Segments.getKnownSegmentsToArchiveAllSites', function (&$segments) {
    $segments[] = 'country=jp;city=Tokyo';
});

Callback Signature:

function(&$segmentsToProcess)

Usages:

SegmentEditor::getKnownSegmentsToArchiveAllSites

Segments.getKnownSegmentsToArchiveForSite

Defined in Piwik/SettingsPiwik in line 134

Triggered during the cron archiving process to collect segments that should be pre-processed for one specific site. The archiving process will be launched for each of these segments when archiving data for that one site.

This event can be used to add segments to be pre-processed for one site.

Note: If you just want to add a segment that is managed by the user, you should use the SegmentEditor API.

Example

Piwik::addAction('Segments.getKnownSegmentsToArchiveForSite', function (&$segments, $idSite) {
    $segments[] = 'country=jp;city=Tokyo';
});

Callback Signature:

function(&$segments, $idSite)

Usages:

SegmentEditor::getKnownSegmentsToArchiveForSite

Site

Site.setSite

Defined in Piwik/Site in line 117

Triggered so plugins can modify website entities without modifying the database. This event should not be used to add data that is expensive to compute. If you need to make HTTP requests or query the database for more information, this is not the place to do it.

Example

Piwik::addAction('Site.setSite', function ($idSite, &$info) {
    $info['name'] .= " (original)";
});

Callback Signature:

function($idSite, &$infoSite)

SitesManager

SitesManager.addSite.end

Defined in Piwik/Plugins/SitesManager/API in line 621

Triggered after a site has been added.

Callback Signature:

function($idSite)

SitesManager.deleteSite.end

Defined in Piwik/Plugins/SitesManager/API in line 676

Triggered after a site has been deleted. Plugins can use this event to remove site specific values or settings, such as removing all goals that belong to a specific website. If you store any data related to a website you should clean up that information here.

Callback Signature:

function($idSite)

Usages:

Goals::deleteSiteGoals, ScheduledReports::deleteSiteReport, UsersManager::deleteSite

SitesManager.getImageTrackingCode

Defined in Piwik/Plugins/SitesManager/API in line 129

Triggered when generating image link tracking code server side. Plugins can use this event to customise the image tracking code that is displayed to the user.

Callback Signature:

function(&$piwikUrl, &$urlParams)

TaskScheduler

TaskScheduler.getScheduledTasks

Defined in Piwik/TaskScheduler in line 94

Callback Signature:

function(&$tasks)

Tracker

Tracker.Cache.getSiteAttributes

Defined in Piwik/Tracker/Cache in line 87

Triggered to get the attributes of a site entity that might be used by the Tracker. Plugins add new site attributes for use in other tracking events must use this event to put those attributes in the Tracker Cache.

Example

public function getSiteAttributes($content, $idSite)
{
    $sql = "SELECT info FROM " . Common::prefixTable('myplugin_extra_site_info') . " WHERE idsite = ?";
    $content['myplugin_site_data'] = Db::fetchOne($sql, array($idSite));
}

Callback Signature:

function(&$content, $idSite)

Usages:

Goals::fetchGoalsFromDb, SitesManager::recordWebsiteDataInCache, UsersManager::recordAdminUsersInCache

Tracker.detectReferrerSearchEngine

Defined in Piwik/Plugins/Referrers/Columns/Base in line 154

Triggered when detecting the search engine of a referrer URL. Plugins can use this event to provide custom search engine detection logic.

Callback Signature:

function(&$searchEngineInformation, $this->referrerUrl)

Tracker.end

Defined in Piwik/Tracker in line 256

Tracker.existingVisitInformation

Defined in Piwik/Tracker/Visit in line 260

Triggered before a visit entity is updated when tracking an action for an existing visit. This event can be used to modify the visit properties that will be updated before the changes are persisted.

Callback Signature:

function(&$valuesToUpdate, $this->visitorInfo)

Tracker.getDatabaseConfig

Defined in Piwik/Tracker in line 565

Triggered before a connection to the database is established by the Tracker. This event can be used to change the database connection settings used by the Tracker.

Callback Signature:

function(&$configDb)

Tracker.isExcludedVisit

Defined in Piwik/Tracker/VisitExcluded in line 85

Triggered on every tracking request. This event can be used to tell the Tracker not to record this particular action or visit.

Callback Signature:

function(&$excluded)

Tracker.makeNewVisitObject

Defined in Piwik/Tracker in line 647

Triggered before a new visit tracking object is created. Subscribers to this event can force the use of a custom visit tracking object that extends from Piwik\Tracker\VisitInterface.

Callback Signature:

function(&$visit)

Tracker.newConversionInformation

Defined in Piwik/Tracker/GoalManager in line 724

Triggered before persisting a new conversion entity. This event can be used to modify conversion information or to add new information to be persisted.

Callback Signature:

function(&$conversion, $visitInformation, $this->request)

Tracker.newVisitorInformation

Defined in Piwik/Tracker/Visit in line 327

Triggered before a new visit entity is persisted. This event can be used to modify the visit entity or add new information to it before it is persisted. The UserCountry plugin, for example, uses this event to add location information for each visit.

Callback Signature:

function(&$this->visitorInfo, $this->request)

Tracker.recordAction

Defined in Piwik/Tracker/Action in line 364

Triggered after successfully persisting a visit action entity.

Callback Signature:

function($trackerAction = $this, $visitAction)

Tracker.recordEcommerceGoal

Defined in Piwik/Tracker/GoalManager in line 317

Triggered after successfully persisting an ecommerce conversion. Note: Subscribers should be wary of doing any expensive computation here as it may slow the tracker down.

Callback Signature:

function($conversion, $visitInformation)

Tracker.recordStandardGoals

Defined in Piwik/Tracker/GoalManager in line 700

Triggered after successfully recording a non-ecommerce conversion. Note: Subscribers should be wary of doing any expensive computation here as it may slow the tracker down.

Callback Signature:

function($conversion)

Tracker.Request.getIdSite

Defined in Piwik/Tracker/Request in line 335

Triggered when obtaining the ID of the site we are tracking a visit for. This event can be used to change the site ID so data is tracked for a different website.

Callback Signature:

function(&$idSite, $this->params)

Tracker.setTrackerCacheGeneral

Defined in Piwik/Tracker/Cache in line 150

Triggered before the general tracker cache is saved to disk. This event can be used to add extra content to the cache.

Data that is used during tracking but is expensive to compute/query should be cached to keep tracking efficient. One example of such data are options that are stored in the piwik_option table. Querying data for each tracking request means an extra unnecessary database query for each visitor action. Using a cache solves this problem.

Example

public function setTrackerCacheGeneral(&$cacheContent)
{
    $cacheContent['MyPlugin.myCacheKey'] = Option::get('MyPlugin_myOption');
}

Callback Signature:

function(&$cacheContent)

Usages:

PrivacyManager::setTrackerCacheGeneral, UserCountry::setTrackerCacheGeneral

Tracker.setVisitorIp

Defined in Piwik/Tracker/Visit in line 99

Triggered after visits are tested for exclusion so plugins can modify the IP address persisted with a visit. This event is primarily used by the PrivacyManager plugin to anonymize IP addresses.

Callback Signature:

function(&$this->visitorInfo['location_ip'])

Translate

Translate.getClientSideTranslationKeys

Defined in Piwik/Translate in line 208

Triggered before generating the JavaScript code that allows i18n strings to be used in the browser. Plugins should subscribe to this event to specify which translations should be available to JavaScript.

Event handlers should add whole translation keys, ie, keys that include the plugin name.

Example

public function getClientSideTranslationKeys(&$result)
{
    $result[] = "MyPlugin_MyTranslation";
}

Callback Signature:

function(&$result)

Usages:

CoreHome::getClientSideTranslationKeys, CorePluginsAdmin::getClientSideTranslationKeys, CoreVisualizations::getClientSideTranslationKeys, Dashboard::getClientSideTranslationKeys, Feedback::getClientSideTranslationKeys, Goals::getClientSideTranslationKeys, Live::getClientSideTranslationKeys, MultiSites::getClientSideTranslationKeys, Overlay::getClientSideTranslationKeys, ScheduledReports::getClientSideTranslationKeys, SitesManager::getClientSideTranslationKeys, Transitions::getClientSideTranslationKeys, UserCountry::getClientSideTranslationKeys, UserCountryMap::getClientSideTranslationKeys, UsersManager::getClientSideTranslationKeys, Widgetize::getClientSideTranslationKeys, ZenMode::getClientSideTranslationKeys

User

User.getLanguage

Defined in Piwik/Translate in line 127

Triggered when the current user's language is requested. By default the current language is determined by the language query parameter. Plugins can override this logic by subscribing to this event.

Example

public function getLanguage(&$lang)
{
    $client = new My3rdPartyAPIClient();
    $thirdPartyLang = $client->getLanguageForUser(Piwik::getCurrentUserLogin());

    if (!empty($thirdPartyLang)) {
        $lang = $thirdPartyLang;
    }
}

Callback Signature:

function(&$lang)

Usages:

LanguagesManager::getLanguageToLoad

User.isNotAuthorized

Defined in Piwik/FrontController in line 99

Triggered when a user with insufficient access permissions tries to view some resource. This event can be used to customize the error that occurs when a user is denied access (for example, displaying an error message, redirecting to a page other than login, etc.).

Callback Signature:

function($exception)

Usages:

Login::noAccess

UsersManager

UsersManager.addUser.end

Defined in Piwik/Plugins/UsersManager/API in line 347

Triggered after a new user is created.

Callback Signature:

function($userLogin, $email, $password, $alias)

UsersManager.checkPassword

Defined in Piwik/Plugins/UsersManager/UsersManager in line 130

Triggered before core password validator check password. This event exists for enable option to create custom password validation rules. It can be used to validate password (length, used chars etc) and to notify about checking password.

Example

Piwik::addAction('UsersManager.checkPassword', function ($password) {
    if (strlen($password) < 10) {
        throw new Exception('Password is too short.');
    }
});

Callback Signature:

function($password)

UsersManager.deleteUser

Defined in Piwik/Plugins/UsersManager/Model in line 255

Triggered after a user has been deleted. This event should be used to clean up any data that is related to the now deleted user. The Dashboard plugin, for example, uses this event to remove the user's dashboards.

Callback Signature:

function($userLogin)

Usages:

CoreAdminHome::cleanupUser, CoreVisualizations::deleteUser, Dashboard::deleteDashboardLayout, LanguagesManager::deleteUserLanguage, ScheduledReports::deleteUserReport

UsersManager.getDefaultDates

Defined in Piwik/Plugins/UsersManager/Controller in line 194

Triggered when the list of available dates is requested, for example for the User Settings > Report date to load by default.

Callback Signature:

function(&$dates)

UsersManager.updateUser.end

Defined in Piwik/Plugins/UsersManager/API in line 452

Triggered after an existing user has been updated. Event notify about password change.

Callback Signature:

function($userLogin, $passwordHasBeenUpdated, $email, $password, $alias)

View

View.ReportsByDimension.render

Defined in Piwik/View/ReportsByDimension in line 99

Triggered before rendering ReportsByDimension views. Plugins can use this event to configure ReportsByDimension instances by adding or removing reports to display.

Callback Signature:

function($this)

ViewDataTable

ViewDataTable.addViewDataTable

Defined in Piwik/ViewDataTable/Manager in line 88

Triggered when gathering all available DataTable visualizations. Plugins that want to expose new DataTable visualizations should subscribe to this event and add visualization class names to the incoming array.

Example

public function addViewDataTable(&$visualizations)
{
    $visualizations[] = 'Piwik\\Plugins\\MyPlugin\\MyVisualization';
}

Callback Signature:

function(&$visualizations)

Usages:

CoreVisualizations::getAvailableDataTableVisualizations

ViewDataTable.configure

Defined in Piwik/Plugin/ViewDataTable in line 251

Triggered during ViewDataTable construction. Subscribers should customize the view based on the report that is being displayed.

Plugins that define their own reports must subscribe to this event in order to specify how the Piwik UI should display the report.

Example

// event handler
public function configureViewDataTable(ViewDataTable $view)
{
    switch ($view->requestConfig->apiMethodToRequestDataTable) {
        case 'VisitTime.getVisitInformationPerServerTime':
            $view->config->enable_sort = true;
            $view->requestConfig->filter_limit = 10;
            break;
    }
}

Callback Signature:

function($this)

Usages:

Actions::configureViewDataTable

WidgetsList

WidgetsList.addWidgets

Defined in Piwik/WidgetsList in line 101