Events

This is a complete list of available hooks.

Access

Access.createAccessSingleton

Defined in Piwik/Access in line 91

Callback Signature:

function(&self::$instance)

API

API.$pluginName.$methodName

Defined in Piwik/API/Proxy in line 208

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)

  • array &$finalParameters List of parameters that will be passed to the API method.

API.$pluginName.$methodName.end

Defined in Piwik/API/Proxy in line 258

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

  • mixed $returnedValue The API method's return value. Can be an object, such as a DataTable instance. could be a DataTable.

  • array $extraInfo An array holding information regarding the API request. Will contain the following data: - className: The namespace-d class name of the API instance that's being called. - module: The name of the plugin the API request was dispatched to. - action: The name of the API method that was executed. - parameters: The array of parameters passed to the API method.

API.DocumentationGenerator.$token

Defined in Piwik/API/Proxy in line 504

This event exists for checking whether a Plugin API class or a Plugin API method tagged with a @hideXYZ should be hidden in the API listing.

Callback Signature:

function(&$hide)

  • bool &$hide whether to hide APIs tagged with $token should be displayed.

API.getReportMetadata.end

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

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)

  • array &$availableReports List of all report metadata. Read the API.getReportMetadata docs to see what this array contains.

  • array $parameters Contains the values of the sites and period we are getting reports for. Some report depend on this data. For example, Goals reports depend on the site IDs being request. Contains the following information: - idSites: The array of site IDs we are getting reports for. - period: The period type, eg, 'day', 'week', 'month', 'year', 'range'. - date: A string date within the period or a date range, eg, '2013-01-01' or '2012-01-01,2013-01-01'.

Usages:

Goals::getReportMetadataEnd

API.getSegmentDimensionMetadata

Defined in Piwik/Plugins/API/API in line 151

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)

  • array $dimensions The list of available segment dimensions. Append to this list to add new segments. Each element in this list must contain the following information: - type: Either 'metric' or 'dimension'. 'metric' means the value is a numeric and 'dimension' means it is a string. Also, 'metric' values will be displayed under Visit (metrics) in the Segment Editor. - category: The segment category name. This can be an existing segment category visible in the segment editor. - name: The pretty name of the segment. Can be a translation token. - segment: The segment name, eg, 'visitIp' or 'searches'. - acceptedValues: A string describing one or two exacmple values, eg '13.54.122.1, etc.'. - sqlSegment: The table column this segment will segment by. For example, 'log_visit.location_ip' for the visitIp segment. - sqlFilter: A PHP callback to apply to segment values before they are used in SQL. - permission: True if the current user has view access to this segment, false if otherwise.

  • array $idSites The list of site IDs we're getting the available segments for. Some segments (such as Goal segments) depend on the site.

Usages:

CustomVariables::getSegmentsMetadata

API.Request.authenticate

Defined in Piwik/API/Request in line 263

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)

  • string $token_auth The value of the token_auth query parameter.

Usages:

Login::ApiRequestAuthenticate

API.Request.dispatch

Defined in Piwik/API/Proxy in line 188

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)

  • array &$finalParameters List of parameters that will be passed to the API method.

  • string $pluginName The name of the plugin the API method belongs to.

  • string $methodName The name of the API method that will be called.

API.Request.dispatch.end

Defined in Piwik/API/Proxy in line 298

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

  • mixed $returnedValue The API method's return value. Can be an object, such as a DataTable instance.

  • array $extraInfo An array holding information regarding the API request. Will contain the following data: - className: The namespace-d class name of the API instance that's being called. - module: The name of the plugin the API request was dispatched to. - action: The name of the API method that was executed. - parameters: The array of parameters passed to the API method.

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)

  • string &$mergedContent The minified and merged JavaScript.

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)

  • string &$mergedContent The merged and minified CSS.

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)

  • string $jsFiles The JavaScript files to load.

Usages:

Actions::getJsFiles, Annotations::getJsFiles, Contents::getJsFiles, CoreAdminHome::getJsFiles, CoreHome::getJsFiles, CorePluginsAdmin::getJsFiles, CoreVisualizations::getJsFiles, Dashboard::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 66

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)

  • string $stylesheets The list of stylesheet paths.

Usages:

Plugin::getStylesheetFiles, Actions::getStylesheetFiles, Annotations::getStylesheetFiles, Contents::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 382

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)

  • Exception $exception The exception thrown from trying to get an option value.

Usages:

Installation::dispatch

Config.NoConfigurationFile

Defined in Piwik/FrontController in line 286

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)

  • Exception $exception The exception that was thrown by Config::getInstance().

Usages:

Installation::dispatch

Console

Console.filterCommands

Defined in Piwik/Console in line 103

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)

  • array &$commands An array containing a list of command class names.

Controller

Controller.$module.$action

Defined in Piwik/FrontController in line 575

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)

  • array &$parameters The arguments passed to the controller action.

Controller.$module.$action.end

Defined in Piwik/FrontController in line 592

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)

  • mixed &$result The result of the controller action.

  • array $parameters The arguments passed to the controller action.

CoreUpdater

CoreUpdater.update.end

Defined in Piwik/Plugins/CoreUpdater/CoreUpdater in line 91

Triggered after Piwik has been updated.

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)

  • int $idSite The ID of the site we're archiving data for.

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)

  • int $idSite The ID of the site we're archiving data for.

CronArchive.filterWebsiteIds

Defined in Piwik/CronArchive in line 912

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)

  • array &$websiteIds The list of website IDs to launch the archiving process for.

CronArchive.init.finish

Defined in Piwik/CronArchive in line 277

This event is triggered after a CronArchive instance is initialized.

Callback Signature:

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

  • array $websiteIds The list of website IDs this CronArchive instance is processing. This will be the entire list of IDs regardless of whether some have already been processed.

Dashboard

Dashboard.changeDefaultDashboardLayout

Defined in Piwik/Plugins/Dashboard/Dashboard in line 102

Allows other plugins to modify the default dashboard layout.

Callback Signature:

function(&$defaultLayout)

  • string &$defaultLayout JSON encoded string of the default dashboard layout. Contains an array of columns where each column is an array of widgets. Each widget is an associative array w/ the following elements: * uniqueId: The widget's unique ID. * parameters: The array of query parameters that should be used to get this widget's report.

Db

Db.cannotConnectToDb

Defined in Piwik/FrontController in line 359

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)

  • Exception $exception The exception thrown from creating and testing the database connection.

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)

  • array

FrontController

FrontController.modifyErrorPage

Defined in Piwik/FrontController in line 645

Triggered before a Piwik error page is displayed to the user. This event can be used to modify the content of the error page that is displayed when an exception is caught.

Callback Signature:

function(&$result, $ex)

  • string &$result The HTML of the error page.

  • Exception $ex The Exception displayed in the error page.

Goals

Goals.getReportsWithGoalMetrics

Defined in Piwik/Plugins/Goals/Goals in line 226

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)

  • array &$reportsWithGoals The list of arrays describing reports that have Goal metrics. Each element of this array must be an array with the following properties: - category: The report category. This should be a translated string. - name: The report's translated name. - module: The plugin the report is in, eg, 'UserCountry'. - action: The API method of the report, eg, 'getCountry'.

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)

  • array &$reports An array containing a report unique id as key and an array of API parameters as values.

Usages:

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

LanguageManager

LanguageManager.getAvailableLanguages

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

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

Callback Signature:

function(&$languages)

  • array

Live

Live.API.getIdSitesString

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

Callback Signature:

function(&$idSites)

Live.getAllVisitorDetails

Defined in Piwik/Plugins/Live/Visitor in line 74

This event can be used to add any details to a visitor. The visitor's details are for instance used in API requests like 'Live.getVisitorProfile' and 'Live.getLastVisitDetails'. This can be useful for instance in case your plugin defines any visit dimensions and you want to add the value of your dimension to a user. It can be also useful if you want to enrich a visitor with custom fields based on other fields or if you want to change or remove any fields from the user.

Example

Piwik::addAction('Live.getAllVisitorDetails', function (&visitor, $details) {
    $visitor['userPoints'] = $details['actions'] + $details['events'] + $details['searches'];
    unset($visitor['anyFieldYouWantToRemove']);
});

Callback Signature:

function(&$visitor, $this->details)

  • array

  • array $details The details array contains all visit dimensions (columns of log_visit table)

Usages:

Actions::extendVisitorDetails, CoreHome::extendVisitorDetails, CustomVariables::extendVisitorDetails, DevicesDetection::extendVisitorDetails, Events::extendVisitorDetails, Provider::extendVisitorDetails, Referrers::extendVisitorDetails, UserCountry::extendVisitorDetails, UserSettings::extendVisitorDetails, VisitTime::extendVisitorDetails, VisitorInterest::extendVisitorDetails

Live.getExtraVisitorDetails

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

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:

  • visitorAvatar: A URL to an image to display in the top left corner of the popup.
  • visitorDescription: Text to be used as the tooltip of the avatar image.

Callback Signature:

function(&$result)

  • array $visitorProfile The unaugmented visitor profile info.

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)

  • \Piwik\Plugins\Live\VisitorInterface &$visitor Initialized to null, but can be set to a new visitor object. If it isn't modified Piwik uses the default class.

  • array $visitorRawData Raw data using in Visitor object constructor.

Log

Log.formatDatabaseMessage

Defined in Piwik/Log in line 657

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)

  • mixed &$message The object that is being logged. Event handlers should check if the object is of a certain type and if it is, set $message to the string that should be logged.

  • int $level The log level used with this log entry.

  • string $tag The current plugin that started logging (or if no plugin, the current class).

  • string $datetime Datetime of the logging call.

  • Log $logger The Log singleton.

Log.formatFileMessage

Defined in Piwik/Log in line 698

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)

  • mixed &$message The object that is being logged. Event handlers should check if the object is of a certain type and if it is, set $message to the string that should be logged.

  • int $level The log level used with this log entry.

  • string $tag The current plugin that started logging (or if no plugin, the current class).

  • string $datetime Datetime of the logging call.

  • Log $logger The Log singleton.

Log.formatScreenMessage

Defined in Piwik/Log in line 603

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)

  • mixed &$message The object that is being logged. Event handlers should check if the object is of a certain type and if it is, set $message to the string that should be logged.

  • int $level The log level used with this log entry.

  • string $tag The current plugin that started logging (or if no plugin, the current class).

  • string $datetime Datetime of the logging call.

  • Log $logger The Log singleton.

Log.getAvailableWriters

Defined in Piwik/Log in line 367

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)

  • array &$writers Array mapping writer names with logging writers.

Login

Login.authenticate

Defined in Piwik/Plugins/Login/SessionInitializer in line 154

Callback Signature:

function($auth->getLogin(), $tokenAuth)

Login.authenticate.successful

Defined in Piwik/Plugins/Login/SessionInitializer in line 207

Callback Signature:

function($authResult->getIdentity(), $authResult->getTokenAuth())

Login.initSession.end

Defined in Piwik/Plugins/Login/SessionInitializer in line 125

Defined in Piwik/Menu/MenuAdmin in line 136

Callback Signature:

function()

Defined in Piwik/Menu/MenuReporting in line 127

Callback Signature:

function()

Defined in Piwik/Menu/MenuTop in line 101

Callback Signature:

function()

Metrics

Metrics.getDefaultMetricDocumentationTranslations

Defined in Piwik/Metrics in line 399

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

Callback Signature:

function(&$translations)

  • string &$translations The array mapping of column_name => Plugin_TranslationForColumnDocumentation

Usages:

Actions::addMetricDocumentationTranslations, Events::addMetricDocumentationTranslations

Metrics.getDefaultMetricTranslations

Defined in Piwik/Metrics in line 289

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

Callback Signature:

function(&$translations)

  • string &$translations The array mapping of column_name => Plugin_TranslationForColumn

Usages:

Actions::addMetricTranslations, Contents::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)

  • string $phoneNumber The phone number that was just deleted.

Usages:

ScheduledReports::deletePhoneNumber

Piwik

Piwik.getJavascriptCode

Defined in Piwik/Tracker/TrackerCodeGenerator in line 126

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

Callback Signature:

function(&$codeImpl, $parameters)

  • array &$codeImpl An array containing snippets of code that the event handler can modify. Will contain the following elements: - idSite: The ID of the site being tracked. - piwikUrl: The tracker URL to use. - options: A string of JavaScript code that customises the JavaScript tracker. - optionsBeforeTrackerUrl: A string of Javascript code that customises the JavaScript tracker inside of anonymous function before adding setTrackerUrl into paq. - protocol: Piwik url protocol. The httpsPiwikUrl element can be set if the HTTPS domain is different from the normal domain.

  • array $parameters The parameters supplied to TrackerCodeGenerator::generate().

Platform

Platform.initialized

Defined in Piwik/FrontController in line 446

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

PluginManager

PluginManager.pluginActivated

Defined in Piwik/Plugin/Manager in line 459

Event triggered after a plugin has been activated.

Callback Signature:

function($pluginName)

  • string $pluginName The plugin that has been activated.

PluginManager.pluginDeactivated

Defined in Piwik/Plugin/Manager in line 300

Event triggered after a plugin has been deactivated.

Callback Signature:

function($pluginName)

  • string $pluginName The plugin that has been deactivated.

Provider

Provider.getCleanHostname

Defined in Piwik/Plugins/Provider/Provider in line 115

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)

  • string &$cleanHostname The hostname string to display. Set by the event handler.

  • string $hostname The full hostname.

Referrer

Referrer.addSearchEngineUrls

Defined in Piwik/Common in line 815

Callback Signature:

function(&$searchEngines)

Referrer.addSocialUrls

Defined in Piwik/Common in line 854

Callback Signature:

function(&$socialUrls)

Request

Request.dispatch

Defined in Piwik/FrontController in line 560

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)

  • string &$module The name of the plugin being dispatched to.

  • string &$action The name of the controller method being dispatched to.

  • array &$parameters The arguments passed to the controller action.

Usages:

Installation::dispatchIfNotInstalledYet

Request.dispatch.end

Defined in Piwik/FrontController in line 602

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)

  • mixed &$result The controller action result.

  • array $parameters The arguments passed to the controller action.

Request.dispatchCoreAndPluginUpdatesScreen

Defined in Piwik/FrontController in line 397

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 Registry to an object that implements the Auth interface.

Example

use Piwik\Registry;

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

Callback Signature:

function($activateCookieAuth = true)

  • bool $activateCookieAuth Whether authentication based on $_COOKIE values should be allowed.

Usages:

Login::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/FrontController in line 419

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 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 773

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)

  • bool &$allowMultipleReports Whether the backend type can handle multiple Piwik reports or not.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

Usages:

MobileMessaging::allowMultipleReports, ScheduledReports::allowMultipleReports

ScheduledReports.getRendererInstance

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

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)

  • ReportRenderer &$reportRenderer This variable should be set to an instance that extends Piwik\ReportRenderer by one of the event subscribers.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

  • string $outputType The output format of the report, eg, 'html', 'pdf', etc.

  • array &$report An array describing the scheduled report that is being generated.

Usages:

MobileMessaging::getRendererInstance, ScheduledReports::getRendererInstance

ScheduledReports.getReportFormats

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

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)

  • array &$reportFormats An array mapping string IDs for each available scheduled report format with icon paths for those formats. Add your new format's ID to this array.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

Usages:

MobileMessaging::getReportFormats, ScheduledReports::getReportFormats

ScheduledReports.getReportMetadata

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

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)

  • array &$availableReportMetadata An array containg report metadata for each supported report.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

  • int $idSite The ID of the site we're getting available reports for.

Usages:

MobileMessaging::getReportMetadata, ScheduledReports::getReportMetadata

ScheduledReports.getReportParameters

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

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)

  • array &$availableParameters The list of available parameters for this report type. This is an array that maps paramater IDs with a boolean that indicates whether the parameter is mandatory or not.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

Usages:

MobileMessaging::getReportParameters, ScheduledReports::getReportParameters

ScheduledReports.getReportRecipients

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

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)

  • array &$recipients An array of strings describing each of the scheduled reports recipients. Can be, for example, a list of email addresses or phone numbers or whatever else your plugin uses.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

  • array $report An array describing the scheduled report that is being generated.

Usages:

MobileMessaging::getReportRecipients, ScheduledReports::getReportRecipients

ScheduledReports.getReportTypes

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

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)

  • array &$reportTypes An array mapping transport medium IDs with the paths to those mediums' icons. Add your new backend's ID to this array.

Usages:

MobileMessaging::getReportTypes, ScheduledReports::getReportTypes

ScheduledReports.processReports

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

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)

  • array &$processedReports The list of processed reports in the scheduled report. Entries includes report data and metadata for each report.

  • string $reportType A string ID describing how the scheduled report will be sent, eg, 'sms' or 'email'.

  • string $outputType The output format of the report, eg, 'html', 'pdf', etc.

  • array $report An array describing the scheduled report that is being generated.

Usages:

ScheduledReports::processReports

ScheduledReports.sendReport

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

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 = basename($outputFilename), $prettyDate, $reportSubject, $reportTitle, $additionalFiles, \Piwik\Period\Factory::build($report['period'], $date), $force)

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

  • array $report An array describing the scheduled report that is being generated.

  • string $contents The contents of the scheduled report that was generated and now should be sent.

  • string $filename The path to the file where the scheduled report has been saved.

  • string $prettyDate A prettified date string for the data within the scheduled report.

  • string $reportSubject A string describing what's in the scheduled report.

  • string $reportTitle The scheduled report's given title (given by a Piwik user).

  • array $additionalFiles The list of additional files that should be sent with this report.

  • Period $period The period for which the report has been generated.

  • boolean $force A report can only be sent once per period. Setting this to true will force to send the report even if it has already been sent.

Usages:

MobileMessaging::sendReport, ScheduledReports::sendReport

ScheduledReports.validateReportParameters

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

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)

  • array &$parameters The list of parameters for the scheduled report.

  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

Usages:

MobileMessaging::validateReportParameters, ScheduledReports::validateReportParameters

SegmentEditor

SegmentEditor.deactivate

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

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)

  • int $idSegment The ID of the segment being deleted.

Usages:

ScheduledReports::segmentDeactivation

SegmentEditor.update

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

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)

  • int $idSegment The ID of the segment which visibility is reduced.

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)

  • array &$segmentsToProcess List of segment definitions, eg, array( 'browserCode=ff;resolution=800x600', 'country=jp;city=Tokyo' ) Add segments to this array in your event handler.

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)

  • array $segmentsToProcess List of segment definitions, eg, array( 'browserCode=ff;resolution=800x600', 'country=JP;city=Tokyo' ) Add segments to this array in your event handler.

  • int $idSite The ID of the site to get segments for.

Usages:

SegmentEditor::getKnownSegmentsToArchiveForSite

Settings

Settings.$pluginName.settingsUpdated

Defined in Piwik/Plugin/Settings in line 185

Triggered after a plugin settings have been updated. Example

Piwik::addAction('Settings.MyPlugin.settingsUpdated', function (Settings $settings) {
    $value = $settings->someSetting->getValue();
    // Do something with the new setting value
});

Callback Signature:

function($this)

  • Settings $settings The plugin settings object.

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)

  • int $idSite The ID of the website entity that will be modified.

  • array &$infoSite The website entity. Learn more.

SitesManager

SitesManager.addSite.end

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

Triggered after a site has been added.

Callback Signature:

function($idSite)

  • int $idSite The ID of the site that was added.

SitesManager.deleteSite.end

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

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)

  • int $idSite The ID of the site being deleted.

Usages:

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

SitesManager.getImageTrackingCode

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

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)

  • string $piwikHost The domain and URL path to the Piwik installation, eg, 'examplepiwik.com/path/to/piwik'.

  • array &$urlParams The query parameters used in the element's src URL. See Piwik's image tracking docs for more info.

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)

  • array &$content Array mapping of site attribute names with values.

  • int $idSite The site ID to get attributes for.

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)

  • array &$searchEngineInformation An array with the following information: - name: The search engine name. - keywords: The search keywords used. This parameter is initialized to the results of Piwik's default search engine detection logic.

  • string

Tracker.end

Defined in Piwik/Tracker in line 238

Tracker.existingVisitInformation

Defined in Piwik/Tracker/Visit in line 268

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)

  • array &$valuesToUpdate Visit entity properties that will be updated.

  • array $visit The entire visit entity. Read this to see what it contains.

Tracker.getDatabaseConfig

Defined in Piwik/Tracker in line 559

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)

  • array $dbInfos Reference to an array containing database connection info, including: - host: The host name or IP address to the MySQL database. - username: The username to use when connecting to the database. - password: The password to use when connecting to the database. - dbname: The name of the Piwik MySQL database. - port: The MySQL database port to use. - adapter: either 'PDO\MYSQL' or 'MYSQLI' - type: The MySQL engine to use, for instance 'InnoDB'

Tracker.isExcludedVisit

Defined in Piwik/Tracker/VisitExcluded in line 84

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)

  • bool &$excluded Whether the request should be excluded or not. Initialized to false. Event subscribers should set it to true in order to exclude the request.

Tracker.makeNewVisitObject

Defined in Piwik/Tracker in line 641

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)

  • \Piwik\Tracker\VisitInterface &$visit Initialized to null, but can be set to a new visit object. If it isn't modified Piwik uses the default class.

Tracker.newConversionInformation

Defined in Piwik/Tracker/GoalManager in line 722

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)

  • array &$conversion The conversion entity. Read this to see what it contains.

  • array $visitInformation The visit entity that we are tracking a conversion for. See what information it contains here.

  • \Piwik\Tracker\Request $request An object describing the tracking request being processed.

Tracker.newVisitorInformation

Defined in Piwik/Tracker/Visit in line 326

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)

  • array $visit The visit entity. Read this to see what information it contains.

  • \Piwik\Tracker\Request $request An object describing the tracking request being processed.

Tracker.recordAction

Defined in Piwik/Tracker/Action in line 387

Triggered after successfully persisting a visit action entity.

Callback Signature:

function($trackerAction = $this, $visitAction)

  • Action $tracker Action The Action tracker instance.

  • array $visitAction The visit action entity that was persisted. Read this to see what it contains.

Tracker.recordEcommerceGoal

Defined in Piwik/Tracker/GoalManager in line 355

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)

  • array $conversion The conversion entity that was just persisted. See what information it contains here.

  • array $visitInformation The visit entity that we are tracking a conversion for. See what information it contains here.

Tracker.recordStandardGoals

Defined in Piwik/Tracker/GoalManager in line 698

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)

  • array $conversion The conversion entity that was just persisted. See what information it contains here.

Tracker.Request.getIdSite

Defined in Piwik/Tracker/Request in line 390

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)

  • int &$idSite Initialized to the value of the idsite query parameter. If a subscriber sets this variable, the value it uses must be greater than 0.

  • array $params The entire array of request parameters in the current tracking request.

Tracker.setTrackerCacheGeneral

Defined in Piwik/Tracker/Cache in line 151

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)

  • array &$cacheContent Array of cached data. Each piece of data must be mapped by name.

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'])

  • string $ip The visitor's IP address.

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)

  • array &$result The whole list of client side translation keys.

Usages:

Annotations::getClientSideTranslationKeys, 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)

  • string &$lang The language that should be used for the current user. Will be initialized to the value of the language query parameter.

Usages:

LanguagesManager::getLanguageToLoad

User.isNotAuthorized

Defined in Piwik/FrontController in line 111

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 359

Triggered after a new user is created.

Callback Signature:

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

  • string $userLogin The new user's login handle.

UsersManager.checkPassword

Defined in Piwik/Plugins/UsersManager/UsersManager in line 146

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)

  • string $password Checking password in plain text.

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)

  • string $userLogin The login handle of the deleted user.

Usages:

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

UsersManager.getDefaultDates

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

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)

  • array &$dates Array of (date => translation)

UsersManager.removeSiteAccess

Defined in Piwik/Plugins/ScheduledReports/tests/ScheduledReportsTest in line 95

Callback Signature:

function('userLogin', function(1, 2))

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.removeSiteAccess

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

Callback Signature:

function($userLogin, $idSites)

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.updateUser.end

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

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

Callback Signature:

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

  • string $userLogin The user's login handle.

  • boolean $passwordHasBeenUpdated Flag containing information about password change.

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)

  • ReportsByDimension $this The view instance.

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)

  • array &$visualizations The array of all available visualizations.

ViewDataTable.configure

Defined in Piwik/Plugin/ViewDataTable in line 256

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, Events::configureViewDataTable

WidgetsList

WidgetsList.addWidgets

Defined in Piwik/WidgetsList in line 101