Skip to content

Latest commit

 

History

History
2206 lines (1245 loc) · 109 KB

Hooks.md

File metadata and controls

2206 lines (1245 loc) · 109 KB
Raw

Events

This is a complete list of available hooks. If you are not familiar with this read our Guide about events.

Actions

Actions.Archiving.addActionMetrics

Defined in Piwik/Plugins/Actions/Metrics in line 81

Callback Signature:

function(&$metricsConfig)

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 503

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 263

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 177

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 319

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 StaticContainer::get('Piwik\Auth')) is setup to use $token_auth when its authenticate() method is executed.

Callback Signature:

function($tokenAuth)
  • 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.

Usages:

CustomAlerts::checkApiPermission

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 109

Callback Signature:

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

AssetManager

AssetManager.filterMergedJavaScripts

Defined in Piwik/Plugins/CoreHome/tests/Integration/CoreHomeTest in line 26

Callback Signature:

function(&$content)

Usages:

CoreHome::filterMergedJavaScripts

AssetManager.filterMergedJavaScripts

Defined in Piwik/Plugins/CoreHome/tests/Integration/CoreHomeTest in line 34

Callback Signature:

function(&$content)

Usages:

CoreHome::filterMergedJavaScripts

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.

Usages:

CoreHome::filterMergedJavaScripts

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 45

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, CustomAlerts::getJavaScriptFiles, 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, TreemapVisualization::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, CustomAlerts::getStylesheetFiles, DBStats::getStylesheetFiles, Dashboard::getStylesheetFiles, ExampleRssWidget::getStylesheetFiles, Feedback::getStylesheetFiles, Goals::getStylesheetFiles, Insights::getStylesheetFiles, Installation::getStylesheetFiles, LanguagesManager::getStylesheetFiles, Live::getStylesheetFiles, Login::getStylesheetFiles, MobileMessaging::getStylesheetFiles, MultiSites::getStylesheetFiles, ScheduledReports::getStylesheetFiles, SegmentEditor::getStylesheetFiles, SitesManager::getStylesheetFiles, Transitions::getStylesheetFiles, TreemapVisualization::getStylesheetFiles, UserCountry::getStylesheetFiles, UserCountryMap::getStylesheetFiles, UsersManager::getStylesheetFiles, VisitsSummary::getStylesheetFiles, Widgetize::getStylesheetFiles, ZenMode::getStylesheetFiles

Config

Config.badConfigurationFile

Defined in Piwik/FrontController in line 269

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/Application/Kernel/EnvironmentValidator in line 75

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, LanguagesManager::initLanguage

Console

Console.filterCommands

Defined in Piwik/Console in line 128

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 492

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 509

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/Updater in line 443

Triggered after Piwik has been updated.

CronArchive

CronArchive.archiveSingleSite.finish

Defined in Piwik/CronArchive in line 360

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 350

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 942

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 311

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 101

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 246

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 84

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

Environment

Environment.bootstrapped

Defined in Piwik/Application/Environment in line 98

FrontController

FrontController.modifyErrorPage

Defined in Piwik/ExceptionHandler in line 101

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 220

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 67

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

Installation

Installation.defaultSettingsForm.init

Defined in Piwik/Plugins/Installation/Controller in line 404

Triggered on initialization of the form to customize default Piwik settings (at the end of the installation process).

Callback Signature:

function($form)
  • \Piwik\Plugins\Installation\FormDefaultSettings $form

Usages:

PrivacyManager::installationFormInit

Installation.defaultSettingsForm.submit

Defined in Piwik/Plugins/Installation/Controller in line 415

Triggered on submission of the form to customize default Piwik settings (at the end of the installation process).

Callback Signature:

function($form)
  • \Piwik\Plugins\Installation\FormDefaultSettings $form

Usages:

PrivacyManager::installationFormSubmit

LanguageManager

LanguageManager.getAvailableLanguages

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

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/Model in line 300

Callback Signature:

function(&$idSites)

Live.getAllVisitorDetails

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

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, DevicePlugins::extendVisitorDetails, DevicesDetection::extendVisitorDetails, Events::extendVisitorDetails, Provider::extendVisitorDetails, Referrers::extendVisitorDetails, Resolution::extendVisitorDetails, UserCountry::extendVisitorDetails, UserLanguage::extendVisitorDetails, VisitTime::extendVisitorDetails, VisitorInterest::extendVisitorDetails

Live.getExtraVisitorDetails

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

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.

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

Measurable

Measurable.beforeSaveSettings

Defined in Piwik/Measurable/MeasurableSettings in line 97

Triggered just before Measurable settings are about to be saved. You can use this event for example to validate not only one setting but multiple ssetting. For example whether username and password matches.

Callback Signature:

function($this, $type, $this->idSite)

  • MeasurableSettings $this

  • \Piwik\Measurable\Type $type

  • int $idSite

Measurable.initMeasurableSettings

Defined in Piwik/Measurable/MeasurableSettings in line 66

This event is posted when generating settings for a Measurable (website). You can add any Measurable settings that you wish to be shown in the Measurable manager (websites manager). If you need to add settings only for eg MobileApp measurables you can use eg $type->getId() === Piwik\Plugins\MobileAppMeasurable\Type::ID and add only settings if the condition is true.

Callback Signature:

function($this, $type, $this->idSite)

  • MeasurableSettings $this

  • \Piwik\Measurable\Type $type

  • int $idSite

Menu

Menu.Admin.addItems

Defined in Piwik/Menu/MenuAdmin in line 118

Callback Signature:

function()

Menu.Reporting.addItems

Defined in Piwik/Menu/MenuReporting in line 128

Callback Signature:

function()

Menu.Top.addItems

Defined in Piwik/Menu/MenuTop in line 71

Callback Signature:

function()

Metrics

Metrics.getDefaultMetricDocumentationTranslations

Defined in Piwik/Metrics in line 417

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 305

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, DevicePlugins::addMetricTranslations, Events::addMetricTranslations, Goals::addMetricTranslations, MultiSites::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:

CustomAlerts::removePhoneNumberFromAllAlerts, ScheduledReports::deletePhoneNumber

Piwik

Piwik.getJavascriptCode

Defined in Piwik/Tracker/TrackerCodeGenerator in line 149

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/Plugins/Widgetize/tests/Integration/WidgetTest in line 51

Usages:

CoreUpdater::updateCheck, LanguagesManager::initLanguage, UsersManager::onPlatformInitialized

Platform.initialized

Defined in Piwik/FrontController in line 339

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, LanguagesManager::initLanguage, UsersManager::onPlatformInitialized

PluginManager

PluginManager.pluginActivated

Defined in Piwik/Plugin/Manager in line 495

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 335

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 113

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 830

Callback Signature:

function(&$searchEngines)

Referrer.addSocialUrls

Defined in Piwik/Common in line 884

Callback Signature:

function(&$socialUrls)

Request

Request.dispatch

Defined in Piwik/FrontController in line 474

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:

CustomAlerts::checkControllerPermission, Installation::dispatchIfNotInstalledYet, SitesManager::redirectDashboardToWelcomePage

Request.dispatch.end

Defined in Piwik/FrontController in line 519

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 284

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, LanguagesManager::initLanguage

Request.getRenamedModuleAndAction

Defined in Piwik/API/Request in line 161

This event is posted in the Request dispatcher and can be used to overwrite the Module and Action to dispatch. This is useful when some Controller methods or API methods have been renamed or moved to another plugin.

Callback Signature:

function(&$module, &$action)

  • $module

  • $action

Usages:

Referrers::renameDeprecatedModuleAndAction, ScheduledReports::renameDeprecatedModuleAndAction

Request.initAuthenticationObject

Defined in Piwik/Plugins/API/tests/Integration/APITest in line 85

Usages:

Login::initAuthenticationObject

Request.initAuthenticationObject

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

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 'Piwik\Auth' object in the container to an object that implements the Auth interface.

Example

use Piwik\Container\StaticContainer;

public function initAuthenticationObject($activateCookieAuth)
{
    StaticContainer::getContainer()->set('Piwik\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/Tracker/Request in line 157

Usages:

Login::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/FrontController in line 308

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() {
    StaticContainer::getContainer()->set('Piwik\Auth', new MyAuthImplementation());
});

Usages:

Login::initAuthenticationObject

ScheduledReports

ScheduledReports.allowMultipleReports

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

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 437

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 850

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 775

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 629

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 881

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 826

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 415

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 565

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 656

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 139

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

SEO

SEO.getMetricsProviders

Defined in Piwik/Plugins/SEO/Metric/Aggregator in line 62

Use this event to register new SEO metrics providers.

Callback Signature:

function(&$providers)
  • array &$providers Contains an array of Piwik\Plugins\SEO\Metric\MetricsProvider instances.

Settings

Settings.$this->pluginName.settingsUpdated

Defined in Piwik/Plugin/Settings in line 223

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.

SitesManager

SitesManager.addSite.end

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

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 679

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:

CustomAlerts::deleteAlertsForSite, Goals::deleteSiteGoals, ScheduledReports::deleteSiteReport, SitesManager::onSiteDeleted, UsersManager::deleteSite

SitesManager.getImageTrackingCode

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

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.

Tracker

Tracker.Cache.getSiteAttributes

Defined in Piwik/Tracker/Cache in line 98

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 160

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/Plugins/QueuedTracking/Commands/Process in line 92

Tracker.end

Defined in Piwik/Tracker in line 103

Tracker.existingVisitInformation

Defined in Piwik/Tracker/Visit in line 290

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/Db in line 262

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.getVisitFieldsToPersist

Defined in Piwik/Tracker/Visitor in line 222

This event collects a list of visit entity properties that should be loaded when reading the existing visit. Properties that appear in this list will be available in other tracking events such as 'onExistingVisit'.

Plugins can use this event to load additional visit entity properties for later use during tracking.

Callback Signature:

function(&$fields)

Tracker.isExcludedVisit

Defined in Piwik/Tracker/VisitExcluded in line 92

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/Visit/Factory in line 38

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 725

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 348

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.PageUrl.getQueryParametersToExclude

Defined in Piwik/Tracker/PageUrl in line 99

Triggered before setting the action url in Piwik\Tracker\Action so plugins can register parameters to be excluded from the tracking URL (e.g. campaign parameters).

Callback Signature:

function(&$parametersToExclude)
  • array &$parametersToExclude An array of parameters to exclude from the tracking url.

Tracker.recordAction

Defined in Piwik/Tracker/Action in line 406

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 358

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 701

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 480

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 162

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 105

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/Translation/Translator in line 167

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, CustomAlerts::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.isNotAuthorized

Defined in Piwik/FrontController in line 107

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 433

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 144

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, CustomAlerts::deleteAlertsForLogin, Dashboard::deleteDashboardLayout, LanguagesManager::deleteUserLanguage, ScheduledReports::deleteUserReport

UsersManager.getDefaultDates

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

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 96

Callback Signature:

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

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.removeSiteAccess

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

Callback Signature:

function($userLogin, $idSites)

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.updateUser.end

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

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 98

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.

Usages:

CoreVisualizations::addViewDataTable, TreemapVisualization::getAvailableVisualizations

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 103