Events

Events

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

"Dashboard

"Dashboard.changeDefaultDashboardLayout"

Defined in Piwik/Plugins/Dashboard/Dashboard in line 206

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.
    

Access

Access.Capability.addCapabilities

Defined in Piwik/Access/CapabilitiesProvider in line 43

Triggered to add new capabilities. Example

public function addCapabilities(&$capabilities)
{
    $capabilities[] = new MyNewCapability();
}

Callback Signature:

function(&$capabilities)
  • \Capability $reports An array of reports

Usages:

TagManager::addCapabilities

Access.Capability.filterCapabilities

Defined in Piwik/Access/CapabilitiesProvider in line 62

Triggered to filter / restrict capabilities. Example

public function filterCapabilities(&$capabilities)
{
    foreach ($capabilities as $index => $capability) {
         if ($capability->getId() === 'tagmanager_write') {}
             unset($capabilities[$index]); // remove the given capability
         }
    }
}

Callback Signature:

function(&$capabilities)
  • \Capability $reports An array of reports

Access.modifyUserAccess

Defined in Piwik/Access in line 302

Triggered after the initial access levels and permissions for the current user are loaded. Use this event to modify the current user's permissions (for example, making sure every user has view access to a specific site). Example

function (&$idsitesByAccess, $login) {
    if ($login == 'somespecialuser') {
        return;
    }

    $idsitesByAccess['view'][] = $mySpecialIdSite;
}

Callback Signature:

function(&$this->idsitesByAccess, $this->login]
  • array &$idsitesByAccess The current user's access levels for individual sites. Maps role and capability IDs to list of site IDs, eg:

                             ```
                             [
                                 'view' => [1, 2, 3],
                                 'write' => [4, 5],
                                 'admin' => [],
                             ]
                             ```
    
  • string $login The current user's login.

Actions

Actions.addActionTypes

Defined in Piwik/Plugins/Actions/Columns/ActionType in line 59

Triggered to determine the available action types Plugin can use this event to add their own action types, so they are available in segmentation The array maps internal ids to readable action type names used in visitor details

Example

public function addActionTypes(&$availableTypes) { $availableTypes[] = array( 'id' => 76, 'name' => 'media_play' ); }

Callback Signature:

function(&$availableTypes]
  • array &$availableTypes

Usages:

Actions::addActionTypes

Actions.Archiving.addActionMetrics

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

Callback Signature:

function(&$metricsConfig)

Usages:

Bandwidth::addActionMetrics, PagePerformance::addActionMetrics

Actions.getCustomActionDimensionFieldsAndJoins

Defined in Piwik/Plugins/Actions/VisitorDetails in line 296

Callback Signature:

function(&$customFields, &$customJoins)

Usages:

Bandwidth::provideActionDimensionFields, Contents::provideActionDimensionFields, CustomDimensions::provideActionDimensionFields, CustomVariables::provideActionDimensionFields, Ecommerce::provideActionDimensionFields, Events::provideActionDimensionFields

API

API.$pluginName.$methodName

Defined in Piwik/API/Proxy in line 228

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 303

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

Defined in Piwik/Plugins/API/Controller in line 191

Triggered to add or modify glossary items. You can either modify one of the existing core categories 'reports' and 'metrics' or add your own category. Example

public function addGlossaryItems(&$glossaryItems)
{
     $glossaryItems['users'] = array('title' => 'Users', 'entries' => array(
         array('name' => 'User1', 'documentation' => 'This user has ...'),
         array('name' => 'User2', 'documentation' => 'This user has ...'),
     ));
     $glossaryItems['reports']['entries'][] = array('name' => 'My Report', 'documentation' => 'This report has ...');
}

Callback Signature:

function(&$glossaryItems)
  • array &$glossaryItems An array containing all glossary items.

Usages:

TagManager::addGlossaryItems

API.DocumentationGenerator.$token

Defined in Piwik/API/Proxy in line 648

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

Defined in Piwik/Plugins/API/API in line 694

If your plugin has pages where you'd like comparison features to be disabled, you can add them via this event. Add the pages as "CategoryId.SubcategoryId". Example

public function getPagesComparisonsDisabledFor(&$pages)
{
    $pages[] = "General_Visitors.MyPlugin_MySubcategory";
    $pages[] = "MyPlugin.myControllerAction"; // if your plugin defines a whole page you want comparison disabled for
}

Callback Signature:

function(&$pages]
  • string &$pages

Usages:

Live::getPagesComparisonsDisabledFor, MultiSites::getPagesComparisonsDisabledFor, Referrers::getPagesComparisonsDisabledFor, Transitions::getPagesComparisonsDisabledFor, UserCountryMap::getPagesComparisonsDisabledFor

API.getReportMetadata.end

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

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:

                     - **idSite**: The site ID 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.Request.authenticate

Defined in Piwik/API/Request in line 447

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, LoginLdap::ApiRequestAuthenticate

API.Request.dispatch

Defined in Piwik/API/Proxy in line 208

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:

AnonymousPiwikUsageMeasurement::logStartTimeOfApiCall, CustomAlerts::checkApiPermission

API.Request.dispatch.end

Defined in Piwik/API/Proxy in line 343

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.end', 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.
    

Usages:

AnonymousPiwikUsageMeasurement::trackApiCall, PagePerformance::enrichApi

API.Request.intercept

Defined in Piwik/API/Proxy in line 243

Triggered before an API request is dispatched. Use this event to intercept an API request and execute your own code instead. If you set $returnedValue in a handler for this event, the original API method will not be executed, and the result will be what you set in the event handler.

Callback Signature:

function(&$returnedValue, $finalParameters, $pluginName, $methodName, $parametersRequest]
  • mixed &$returnedValue Set this to set the result and preempt normal API invocation.

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

  • array $parametersRequest The query parameters for this request.

ArchiveProcessor

ArchiveProcessor.ComputeNbUniques.getIdSites

Defined in Piwik/ArchiveProcessor in line 594

Triggered to change which site ids should be looked at when processing unique visitors and users.

Callback Signature:

function(&$sites, $params->getPeriod(), $params->getSegment())
  • array &$idSites An array with one idSite. This site is being archived currently. To cancel the query you can change this value to an empty array. To include other sites in the query you can add more idSites to this list of idSites.

  • Period $period The period that is being requested to be archived.

  • Segment $segment The segment that is request to be archived.

ArchiveProcessor.getArchive

Defined in Piwik/ArchiveProcessor in line 130

Callback Signature:

function($this->archive]

ArchiveProcessor.Parameters.getIdSites

Defined in Piwik/ArchiveProcessor/Parameters in line 165

Callback Signature:

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

ArchiveProcessor.shouldAggregateFromRawData

Defined in Piwik/ArchiveProcessor/PluginsArchiver in line 91

Triggered to detect if the archiver should aggregate from raw data by using MySQL queries (when true) or by aggregate archives (when false). Typically, data is aggregated from raw data for "day" period, and aggregregated from archives for all other periods.

Callback Signature:

function(&$shouldAggregateFromRawData, $this->params)
  • bool &$shouldAggregateFromRawData Set to true, to aggregate from raw data, or false to aggregate multiple reports.

  • Parameters $params

Archiver

Archiver.addRecordBuilders

Defined in Piwik/Plugin/Archiver in line 143

Triggered to add new RecordBuilders that cannot be picked up automatically by the platform. If you define RecordBuilders that take a parameter, for example, an ID to an entity your plugin manages, use this event to add instances of that RecordBuilder to the global list.

Example

public function addRecordBuilders(&$recordBuilders)
{
    $recordBuilders[] = new MyParameterizedRecordBuilder($idOfThingToArchiveFor);
}

Callback Signature:

function(&$recordBuilders]
  • \ArchiveProcessor\RecordBuilder &$recordBuilders An array of RecordBuilder instances

Usages:

CustomDimensions::addRecordBuilders, Goals::addRecordBuilders

Archiver.filterRecordBuilders

Defined in Piwik/Plugin/Archiver in line 165

Triggered to filter / restrict reports. Example

public function filterRecordBuilders(&$recordBuilders)
{
    foreach ($reports as $index => $recordBuilder) {
         if ($recordBuilders instanceof AnotherPluginRecordBuilder) {
             unset($reports[$index]);
         }
    }
}

Callback Signature:

function(&$recordBuilders]
  • \ArchiveProcessor\RecordBuilder &$recordBuilders An array of RecordBuilder instances

Archiving

Archiving.getIdSitesToArchiveWhenNoVisits

Defined in Piwik/ArchiveProcessor/Loader in line 430

Callback Signature:

function(&$idSites)

Archiving.getIdSitesToMarkArchivesAsInvalidated

Defined in Piwik/Plugins/PrivacyManager/Model/DataSubjects in line 139

Callback Signature:

function(&$idSites, $visitDates, null, null, null, $isPrivacyDeleteData = true)

Archiving.getIdSitesToMarkArchivesAsInvalidated

Defined in Piwik/Archive/ArchiveInvalidator in line 335

Triggered when a Matomo user requested the invalidation of some reporting archives. Using this event, plugin developers can automatically invalidate another site, when a site is being invalidated. A plugin may even remove an idSite from the list of sites that should be invalidated to prevent it from ever being invalidated. Example

public function getIdSitesToMarkArchivesAsInvalidates(&$idSites)
{
    if (in_array(1, $idSites)) {
        $idSites[] = 5; // when idSite 1 is being invalidated, also invalidate idSite 5
    }
}

Callback Signature:

function(&$idSites, $dates, $period, $segment, $name, $isPrivacyDeleteData = false)
  • array &$idSites An array containing a list of site IDs which are requested to be invalidated.

  • array $dates An array containing the dates to invalidate.

  • string $period A string containing the period to be invalidated.

  • \Segment $segment A Segment Object containing segment to invalidate.

  • string $name A string containing the name of the archive to be invalidated.

  • bool $isPrivacyDeleteData A boolean value if event is triggered via Privacy delete visit action.

Archiving.makeNewArchiverObject

Defined in Piwik/ArchiveProcessor/PluginsArchiver in line 361

Triggered right after a new plugin archiver instance is created. Subscribers to this event can configure the plugin archiver, for example prevent the archiving of a plugin's data by calling $archiver->disable() method.

Callback Signature:

function($archiver, $pluginName, $this->params, false)
  • Archiver &$archiver The newly created plugin archiver instance.

  • string $pluginName The name of plugin of which archiver instance was created.

  • array $this->params Array containing archive parameters (Site, Period, Date and Segment)

  • bool false This parameter is deprecated and will be removed.

AssetManager

AssetManager.addStylesheets

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

Triggered after all less stylesheets are concatenated into one long string but before it is minified and merged into one file. This event can be used to add less stylesheets that are not located in a file on the disc.

Callback Signature:

function(&$concatenatedContent)
  • string &$concatenatedContent The content of all concatenated less files.

Usages:

CoreHome::addStylesheets

AssetManager.filterMergedJavaScripts

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

Callback Signature:

function(&$content)

Usages:

CoreHome::filterMergedJavaScripts

AssetManager.filterMergedJavaScripts

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

Callback Signature:

function(&$content)

Usages:

CoreHome::filterMergedJavaScripts

AssetManager.filterMergedJavaScripts

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

Triggered after all the JavaScript files Matomo (formerly 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 145

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 43

Triggered when gathering the list of all JavaScript files needed by Matomo 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, AnonymousPiwikUsageMeasurement::getJsFiles, Contents::getJsFiles, CoreAdminHome::getJsFiles, CoreHome::getJsFiles, CorePluginsAdmin::getJsFiles, CoreVisualizations::getJsFiles, CoreVue::getJsFiles, CustomAlerts::getJavaScriptFiles, CustomDimensions::getJsFiles, Dashboard::getJsFiles, Feedback::getJsFiles, Insights::getJsFiles, Live::getJsFiles, LogViewer::getJsFiles, Login::getJsFiles, LoginLdap::getJsFiles, Marketplace::getJsFiles, Overlay::getJsFiles, PagePerformance::getJsFiles, Referrers::getJsFiles, SEO::getJsFiles, ScheduledReports::getJsFiles, SegmentEditor::getJsFiles, TagManager::getJsFiles, Tour::getJsFiles, Transitions::getJsFiles, TreemapVisualization::getJsFiles, TwoFactorAuth::getJsFiles, UserCountry::getJsFiles, UserCountryMap::getJsFiles, UserId::getJavaScriptFiles, Widgetize::getJsFiles

AssetManager.getStylesheetFiles

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

Triggered when gathering the list of all stylesheets (CSS and LESS) needed by Matomo 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, Annotations::getStylesheetFiles, CoreAdminHome::getStylesheetFiles, CoreHome::getStylesheetFiles, CorePluginsAdmin::getStylesheetFiles, CoreVisualizations::getStylesheetFiles, CustomAlerts::getStylesheetFiles, CustomDimensions::getStylesheetFiles, CustomVariables::getStylesheetFiles, DBStats::getStylesheetFiles, Dashboard::getStylesheetFiles, DevicesDetection::getStylesheetFiles, Diagnostics::getStylesheetFiles, Events::getStylesheetFiles, Feedback::getStylesheetFiles, Goals::getStylesheetFiles, Insights::getStylesheetFiles, Installation::getStylesheetFiles, JsTrackerInstallCheck::getStylesheetFiles, Live::getStylesheetFiles, LogViewer::getStylesheetFiles, Login::getStylesheetFiles, LoginLdap::getStylesheetFiles, MarketingCampaignsReporting::getStylesheetFiles, Marketplace::getStylesheetFiles, MobileMessaging::getStylesheetFiles, MultiSites::getStylesheetFiles, PrivacyManager::getStylesheetFiles, ProfessionalServices::getStylesheetFiles, Referrers::getStylesheetFiles, RssWidget::getStylesheetFiles, ScheduledReports::getStylesheetFiles, SecurityInfo::getStylesheetFiles, SegmentEditor::getStylesheetFiles, SitesManager::getStylesheetFiles, TagManager::getStylesheetFiles, Tour::getStylesheetFiles, Transitions::getStylesheetFiles, TreemapVisualization::getStylesheetFiles, TwoFactorAuth::getStylesheetFiles, UserCountry::getStylesheetFiles, UserCountryMap::getStylesheetFiles, UsersManager::getStylesheetFiles, VisitsSummary::getStylesheetFiles, Widgetize::getStylesheetFiles

Category

Category.addSubcategories

Defined in Piwik/Plugin/Categories in line 61

Triggered to add custom subcategories. Example

public function addSubcategories(&$subcategories)
{
    $subcategory = new Subcategory();
    $subcategory->setId('General_Overview');
    $subcategory->setCategoryId('General_Visits');
    $subcategory->setOrder(5);
    $subcategories[] = $subcategory;
}

Callback Signature:

function(&$subcategories)
  • array &$subcategories An array containing a list of subcategories.

Usages:

CustomDimensions::addSubcategories, Dashboard::addSubcategories, Goals::addSubcategories

Changes

Changes.filterChanges

Defined in Piwik/Changes/Model in line 230

Event triggered before changes are displayed Can be used to filter out unwanted changes

Example

Piwik::addAction('Changes.filterChanges', function ($changes) {
    foreach ($changes as $k => $c) {
        // Hide changes for the CoreHome plugin
        if (isset($c['plugin_name']) && $c['plugin_name'] == 'CoreHome') {
             unset($changes[$k]);
        }
    }
});

Callback Signature:

function(&$changes)
  • array &$changes

CliMulti

CliMulti.supportsAsync

Defined in Piwik/CliMulti in line 311

Triggered to allow plugins to force the usage of async cli multi execution or to disable it. Example

public function supportsAsync(&$supportsAsync)
{
    $supportsAsync = false; // do not allow async climulti execution
}

Callback Signature:

function(&$supportsAsync)
  • bool &$supportsAsync Whether async is supported or not.

Config

Config.badConfigurationFile

Defined in Piwik/FrontController in line 370

Triggered when Matomo 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.beforeSave

Defined in Piwik/Config/IniFileChain in line 549

Triggered before a config is being written / saved on the local file system. A plugin can listen to it and modify which settings will be saved on the file system. This allows you to prevent saving config values that a plugin sets on demand. Say you configure the database password in the config on demand in your plugin, then you could prevent that the password is saved in the actual config file by listening to this event like this:

Example function doNotSaveDbPassword (&$values) { unset($values['database']['password']); }

Callback Signature:

function(&$values]
  • array &$values Config values that will be saved

Config.NoConfigurationFile

Defined in Piwik/Application/Kernel/EnvironmentValidator in line 109

Triggered when the configuration file cannot be found or read, which usually means Matomo 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 212

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 635

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 652

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.

Controller.triggerAdminNotifications

Defined in Piwik/Plugin/ControllerAdmin in line 400

Posted when rendering an admin page and notifications about any warnings or errors should be triggered. You can use it for example when you have a plugin that needs to be configured in order to work and the plugin has not been configured yet. It can be also used to cancel / remove other notifications by calling eg Notification\Manager::cancel($notificationId).

Example

public function onTriggerAdminNotifications(Piwik\Widget\WidgetsList $list)
{
    if ($pluginFooIsNotConfigured) {
         $notification = new Notification('The plugin foo has not been configured yet');
         $notification->context = Notification::CONTEXT_WARNING;
         Notification\Manager::notify('fooNotConfigured', $notification);
    }
}

Core

Core.configFileChanged

Defined in Piwik/Config in line 427

Triggered when a INI config file is changed on disk.

Callback Signature:

function($localPath]
  • string $localPath Absolute path to the changed file on the server.

Core.configFileDeleted

Defined in Piwik/Config/Cache in line 87

Callback Signature:

function($this->getFilename($id)]

Core.configFileSanityCheckFailed

Defined in Piwik/Config in line 491

Triggered when the INI config file was not written correctly with the expected content.

Callback Signature:

function($localPath]
  • string $localPath Absolute path to the changed file on the server.

CoreAdminHome

CoreAdminHome.customLogoChanged

Defined in Piwik/Plugins/CoreAdminHome/CustomLogo in line 235

Triggered when a user uploads a custom logo. This event is triggered for the large logo, for the smaller logo-header.png file, and for the favicon.

Callback Signature:

function($absolutePath]
  • string $absolutePath The absolute path to the logo file on the Matomo server.

CoreUpdater

CoreUpdater.update.end

Defined in Piwik/Updater in line 523

Triggered after Matomo has been updated.

Usages:

CustomJsTracker::updateTracker, TagManager::onPluginActivateOrInstall

CronArchive

CronArchive.archiveSingleSite.finish

Defined in Piwik/CronArchive/QueueConsumer in line 327

This event is triggered immediately after the cron archiving process starts archiving data for a single site. Note: multiple archiving processes can post this event.

Callback Signature:

function($this->idSite, $this->pid)
  • int $idSite The ID of the site we're archiving data for.

  • string $pid The PID of the process processing archives for this site.

CronArchive.archiveSingleSite.start

Defined in Piwik/CronArchive/QueueConsumer in line 175

This event is triggered before the cron archiving process starts archiving data for a single site. Note: multiple archiving processes can post this event.

Callback Signature:

function($this->idSite, $this->pid)
  • int $idSite The ID of the site we're archiving data for.

  • string $pid The PID of the process processing archives for this site.

CronArchive.end

Defined in Piwik/CronArchive in line 625

This event is triggered after archiving.

Callback Signature:

function($this]
  • \CronArchive $this

CronArchive.filterWebsiteIds

Defined in Piwik/CronArchive in line 804

Triggered by the core:archive console command so plugins can modify the priority 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.getIdSitesNotUsingTracker

Defined in Piwik/ArchiveProcessor/Loader in line 570

This event is triggered when detecting whether there are sites that do not use the tracker. By default we only archive a site when there was actually any visit since the last archiving. However, some plugins do import data from another source instead of using the tracker and therefore will never have any visits for this site. To make sure we still archive data for such a site when archiving for this site is requested, you can listen to this event and add the idSite to the list of sites that do not use the tracker.

Callback Signature:

function(&$idSitesNotUsingTracker)
  • bool &$idSitesNotUsingTracker The list of idSites that rather import data instead of using the tracker

CronArchive.init.finish

Defined in Piwik/CronArchive in line 337

This event is triggered after a CronArchive instance is initialized.

Callback Signature:

function($this->allWebsites]
  • 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.

CronArchive.init.start

Defined in Piwik/CronArchive in line 294

This event is triggered during initializing archiving.

Callback Signature:

function($this]
  • \CronArchive $this

CustomJsTracker

CustomJsTracker.manipulateJsTracker

Defined in Piwik/Plugins/CustomJsTracker/TrackingCode/PiwikJsManipulator in line 56

Triggered after the Matomo JavaScript tracker has been generated and shortly before the tracker file is written to disk. You can listen to this event to for example automatically append some code to the JS tracker file. Example

function onManipulateJsTracker (&$content) {
    $content .= "\nPiwik.DOM.onLoad(function () { console.log('loaded'); });";
}

Callback Signature:

function(&$content)
  • string &$content the generated JavaScript tracker code

CustomJsTracker.shouldAddTrackerFile

Defined in Piwik/Plugins/CustomJsTracker/TrackingCode/PluginTrackerFiles in line 85

Detect if a custom tracker file should be added to the piwik.js tracker or not. This is useful for example if a plugin only wants to add its tracker file when the plugin is configured.

Callback Signature:

function(&$shouldAddFile, $pluginName)
  • bool &$shouldAddFile Decides whether the tracker file belonging to the given plugin should be added or not.

  • string $pluginName The name of the plugin this file belongs to

Usages:

PrivacyManager::shouldAddTrackerFile

CustomJsTracker.trackerJsChanged

Defined in Piwik/Plugins/CustomJsTracker/TrackerUpdater in line 142

Triggered after the tracker JavaScript content (the content of the piwik.js file) is changed.

Callback Signature:

function($savedFile]
  • string $absolutePath The path to the new piwik.js file.

Usages:

TagManager::regenerateReleasedContainers

CustomJsTracker.trackerJsChanged

Defined in Piwik/Plugins/CustomJsTracker/TrackerUpdater in line 159

Callback Signature:

function($savedFile]

Usages:

TagManager::regenerateReleasedContainers

CustomJsTracker.updateTracker

Defined in Piwik/Plugins/PrivacyManager/API in line 236

Usages:

CustomJsTracker::updateTracker

Db

Db.cannotConnectToDb

Defined in Piwik/FrontController in line 347

Triggered when Matomo 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.getActionReferenceColumnsByTable

Defined in Piwik/Plugin/Dimension/DimensionMetadataProvider in line 92

Triggered when detecting which log_action entries to keep. Any log tables that use the log_action table to reference text via an ID should add their table info so no actions that are still in use will be accidentally deleted. Example

Piwik::addAction('Db.getActionReferenceColumnsByTable', function(&$result) {
    $tableNameUnprefixed = 'log_example';
    $columnNameThatReferencesIdActionInLogActionTable = 'idaction_example';
    $result[$tableNameUnprefixed] = array($columnNameThatReferencesIdActionInLogActionTable);
});

Callback Signature:

function(&$result)
  • array &$result

Db.getDatabaseConfig

Defined in Piwik/Db in line 127

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 *$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 Matomo MySQL database.
                   - **port**: The MySQL database port to use.
                   - **adapter**: either `'PDO\MYSQL'` or `'MYSQLI'`
                   - **type**: The MySQL engine to use, for instance 'InnoDB'
    

Db.getTablesInstalled

Defined in Piwik/Db/Schema/Mysql in line 480

Callback Signature:

function(&$allMyTables]

Usages:

AnonymousPiwikUsageMeasurement::getTablesInstalled, CustomAlerts::getTablesInstalled, CustomDimensions::getTablesInstalled, Dashboard::getTablesInstalled, ExampleLogTables::getTablesInstalled, LanguagesManager::getTablesInstalled, PrivacyManager::getTablesInstalled, QueuedTracking::getTablesInstalled, ScheduledReports::getTablesInstalled, SegmentEditor::getTablesInstalled, TagManager::getTablesInstalled

Dimension

Dimension.addDimensions

Defined in Piwik/Columns/Dimension in line 721

Triggered to add new dimensions that cannot be picked up automatically by the platform. This is useful if the plugin allows a user to create reports / dimensions dynamically. For example CustomDimensions or CustomVariables. There are a variable number of dimensions in this case and it wouldn't be really possible to create a report file for one of these dimensions as it is not known how many Custom Dimensions will exist.

Example

public function addDimension(&$dimensions)
{
    $dimensions[] = new MyCustomDimension();
}

Callback Signature:

function(&$instances)

Usages:

CustomDimensions::addDimensions, CustomVariables::addDimensions

Dimension.filterDimensions

Defined in Piwik/Columns/Dimension in line 745

Triggered to filter / restrict dimensions. Example

public function filterDimensions(&$dimensions)
{
    foreach ($dimensions as $index => $dimension) {
         if ($dimension->getName() === 'Page URL') {}
             unset($dimensions[$index]); // remove this dimension
         }
    }
}

Callback Signature:

function(&$instances)
  • Dimension $dimensions An array of dimensions

Environment

Environment.bootstrapped

Defined in Piwik/Application/Environment in line 104

Feedback

Feedback.showQuestionBanner

Defined in Piwik/Plugins/Feedback/Feedback in line 133

Callback Signature:

function(&$shouldShowQuestionBanner]

Filesystem

Filesystem.allCachesCleared

Defined in Piwik/Filesystem in line 55

Triggered after all non-memory caches are cleared (eg, via the cache:clear command).

FrontController

FrontController.modifyErrorPage

Defined in Piwik/ExceptionHandler in line 188

Triggered before a Matomo 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.

Http

Http.sendHttpRequest

Defined in Piwik/Http in line 331

Triggered to send an HTTP request. Allows plugins to resolve the HTTP request themselves or to find out when an HTTP request is triggered to log this information for example to a monitoring tool.

Callback Signature:

function($aUrl, $httpEventParams, &$response, &$status, &$headers)
  • string $url The URL that needs to be requested

  • array $params HTTP params like - 'httpMethod' (eg GET, POST, ...), - 'body' the request body if the HTTP method needs to be posted - 'userAgent' - 'timeout' After how many seconds a request should time out - 'headers' An array of header strings like array('Accept-Language: en', '...') - 'verifySsl' A boolean whether SSL certificate should be verified - 'destinationPath' If set, the response of the HTTP request should be saved to this file

  • string &$response A plugin listening to this event should assign the HTTP response it received to this variable, for example "{value: true}"

  • string &$status A plugin listening to this event should assign the HTTP status code it received to this variable, for example "200"

  • array &$headers A plugin listening to this event should assign the HTTP headers it received to this variable, eg array('Content-Length' => '5')

Http.sendHttpRequest.end

Defined in Piwik/Http in line 812

Triggered when an HTTP request finished. A plugin can for example listen to this and alter the response, status code, or finish a timer in case the plugin is measuring how long it took to execute the request

Callback Signature:

function($aUrl, $httpEventParams, &$response, &$status, &$headers)
  • string $url The URL that needs to be requested

  • array $params HTTP params like - 'httpMethod' (eg GET, POST, ...), - 'body' the request body if the HTTP method needs to be posted - 'userAgent' - 'timeout' After how many seconds a request should time out - 'headers' An array of header strings like array('Accept-Language: en', '...') - 'verifySsl' A boolean whether SSL certificate should be verified - 'destinationPath' If set, the response of the HTTP request should be saved to this file

  • string &$response The response of the HTTP request, for example "{value: true}"

  • string &$status The returned HTTP status code, for example "200"

  • array &$headers The returned headers, eg array('Content-Length' => '5')

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, MarketingCampaignsReporting::addReportToInsightsOverview, Referrers::addReportToInsightsOverview, UserCountry::addReportToInsightsOverview

Installation

Installation.defaultSettingsForm.init

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

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

Callback Signature:

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

Usages:

GeoIp2::installationFormInit, PrivacyManager::installationFormInit

Installation.defaultSettingsForm.submit

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

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

Callback Signature:

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

Usages:

GeoIp2::installationFormSubmit, PrivacyManager::installationFormSubmit

LanguagesManager

LanguagesManager.getAvailableLanguages

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

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

Callback Signature:

function(&$languages)
  • array

Live

Live.addProfileSummaries

Defined in Piwik/Plugins/Live/ProfileSummaryProvider in line 58

Triggered to add new live profile summaries. Example

public function addProfileSummary(&$profileSummaries)
{
    $profileSummaries[] = new MyCustomProfileSummary();
}

Callback Signature:

function(&$instances)
  • \ProfileSummaryAbstract $profileSummaries An array of profile summaries

Live.addVisitorDetails

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

Triggered to add new visitor details that cannot be picked up by the platform automatically. Example

public function addVisitorDetails(&$visitorDetails)
{
    $visitorDetails[] = new CustomVisitorDetails();
}

Callback Signature:

function(&$instances)

Live.API.getIdSitesString

Defined in Piwik/Plugins/Live/Model in line 449

Callback Signature:

function(&$idSites)

Live.filterProfileSummaries

Defined in Piwik/Plugins/Live/ProfileSummaryProvider in line 80

Triggered to filter / restrict profile summaries. Example

public function filterProfileSummary(&$profileSummaries)
{
    foreach ($profileSummaries as $index => $profileSummary) {
         if ($profileSummary->getId() === 'myid') {}
             unset($profileSummaries[$index]); // remove all summaries having this ID
         }
    }
}

Callback Signature:

function(&$instances)
  • \ProfileSummaryAbstract $profileSummaries An array of profile summaries

Live.filterVisitorDetails

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

Triggered to filter / restrict vistor details. Example

public function filterVisitorDetails(&$visitorDetails)
{
    foreach ($visitorDetails as $index => $visitorDetail) {
         if (strpos(get_class($visitorDetail), 'MyPluginName') !== false) {}
             unset($visitorDetails[$index]); // remove all visitor details for a specific plugin
         }
    }
}

Callback Signature:

function(&$instances)

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 Matomo uses the default class.

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

Login

Login.authenticate

Defined in Piwik/Session/SessionInitializer in line 58

Callback Signature:

function($auth->getLogin())

Login.authenticate

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

Callback Signature:

function($auth->getLogin())

Login.authenticate.failed

Defined in Piwik/Session/SessionInitializer in line 36

Callback Signature:

function($auth->getLogin())

Usages:

Login::onFailedLoginRecordAttempt

Login.authenticate.failed

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

Callback Signature:

function($auth->getLogin())

Usages:

Login::onFailedLoginRecordAttempt

Login.authenticate.successful

Defined in Piwik/Session/SessionInitializer in line 41

Callback Signature:

function($auth->getLogin())

Usages:

Login::beforeLoginCheckBruteForce

Login.authenticate.successful

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

Callback Signature:

function($auth->getLogin())

Usages:

Login::beforeLoginCheckBruteForce

Login.logout

Defined in Piwik/Plugins/Login/Controller in line 528

Callback Signature:

function(Piwik::getCurrentUserLogin()]

Login.userRequiresPasswordConfirmation

Defined in Piwik/Piwik in line 311

Triggered to check if a password confirmation for a user is required. This event can be used in custom login plugins to skip the password confirmation checks for certain users, where e.g. no password would be available.

Attention: Use this event wisely. Disabling password confirmation decreases the security.

Callback Signature:

function(&$requiresPasswordConfirmation, $login]
  • bool &$requiresPasswordConfirmation Indicates if the password should be checked or not

  • string $login Login of a user the password should be confirmed for

Usages:

LoginLdap::skipPasswordConfirmation

Mail

Mail.send

Defined in Piwik/Mail in line 294

This event is posted right before an email is sent. You can use it to customize the email by, for example, replacing the subject/body, changing the from address, etc.

Callback Signature:

function($mail]
  • Mail $mail The Mail instance that is about to be sent.

Mail.shouldSend

Defined in Piwik/Mail in line 406

This event is posted before sending an email. You can use it to abort sending a specific email, if you want.

Callback Signature:

function(&$shouldSendMail, $mail]
  • bool &$shouldSendMail Whether to send this email or not. Set to false to skip sending.

  • Mail $mail The Mail instance that will be sent.

MeasurableSettings

MeasurableSettings.updated

Defined in Piwik/Settings/Measurable/MeasurableSettings in line 137

Triggered after a plugin settings have been updated. Example

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

Callback Signature:

function($this, $this->idSite)
  • \Settings $settings The plugin settings object.

Metric

Metric.addComputedMetrics

Defined in Piwik/Columns/MetricsList in line 152

Triggered to add new metrics that cannot be picked up automatically by the platform. This is useful if the plugin allows a user to create metrics dynamically. For example CustomDimensions or CustomVariables.

Example

public function addMetric(&$list)
{
    $list->addMetric(new MyCustomMetric());
}

Callback Signature:

function($list, $computedFactory)
  • MetricsList $list An instance of the MetricsList. You can add metrics to the list this way.

Usages:

CoreHome::addComputedMetrics, Ecommerce::addComputedMetrics, Goals::addComputedMetrics

Metric.addMetrics

Defined in Piwik/Columns/MetricsList in line 128

Triggered to add new metrics that cannot be picked up automatically by the platform. This is useful if the plugin allows a user to create metrics dynamically. For example CustomDimensions or CustomVariables.

Example

public function addMetric(&$list)
{
    $list->addMetric(new MyCustomMetric());
}

Callback Signature:

function($list)
  • MetricsList $list An instance of the MetricsList. You can add metrics to the list this way.

Usages:

Goals::addMetrics

Metric.filterMetrics

Defined in Piwik/Columns/MetricsList in line 166

Triggered to filter metrics. Example

public function removeMetrics(Piwik\Columns\MetricsList $list)
{
    $list->remove($category='General_Visits'); // remove all metrics having this category
}

Callback Signature:

function($list)
  • MetricsList $list An instance of the MetricsList. You can change the list of metrics this way.

Metrics

Metrics.getDefaultMetricDocumentationTranslations

Defined in Piwik/Metrics in line 571

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, Contents::addMetricDocumentationTranslations, Events::addMetricDocumentationTranslations

Metrics.getDefaultMetricSemanticTypes

Defined in Piwik/Metrics in line 400

Use this event to notify Matomo of the semantic types of metrics your plugin adds. A metric's semantic type is metadata used primarily in integrations with Matomo and third party services/applications. It provides information that can be used to determine how to display or use the information.

It is recommended for your plugin to provide this information so users of third party services that connect with Matomo can make full use of the data your plugin tracks.

See Metrics for the list of available semantic types.

Callback Signature:

function(&$types]
  • string &$types The array mapping of metric_name => metric semantic type

Usages:

Actions::addMetricSemanticTypes, Bandwidth::addMetricSemanticTypes, Contents::addMetricSemanticTypes, Events::addMetricSemanticTypes, Goals::addMetricSemanticTypes, PagePerformance::addMetricSemanticTypes, Referrers::addMetricSemanticTypes, VisitFrequency::addMetricSemanticTypes

Metrics.getDefaultMetricTranslations

Defined in Piwik/Metrics in line 459

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, Bandwidth::addMetricTranslations, Contents::addMetricTranslations, DevicePlugins::addMetricTranslations, Events::addMetricTranslations, Goals::addMetricTranslations, MultiSites::addMetricTranslations, PagePerformance::addMetricTranslations, Referrers::getDefaultMetricTranslations, VisitFrequency::addMetricTranslations

Metrics.getEvolutionUnit

Defined in Piwik/Metrics in line 326

Use this event to define units for custom metrics used in evolution graphs and row evolution only.

Callback Signature:

function(&$unit, $column, $idSite]
  • string &$unit should hold the unit (e.g. %, €, s or empty string)

  • string $column name of the column to determine

  • string $idSite id of the current site

Usages:

Bandwidth::getEvolutionUnit

Metrics.isLowerValueBetter

Defined in Piwik/Metrics in line 283

Use this event to define if a lower value of a metric is better.

Callback Signature:

function(&$isLowerBetter, $column]
  • string &$isLowerBetter should be set to a boolean indicating if lower is better

  • string $column name of the column to determine

Example

public function checkIsLowerMetricValueBetter(&$isLowerBetter, $metric) { if ($metric === 'position') { $isLowerBetter = true; } }

Usages:

PagePerformance::isLowerValueBetter

MobileMessaging

MobileMessaging.deletePhoneNumber

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

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

MultiSites

MultiSites.filterRowsForTotalsCalculation

Defined in Piwik/Plugins/MultiSites/API in line 565

Triggered to filter / restrict which rows should be included in the MultiSites (All Websites Dashboard) totals calculation Example

public function filterMultiSitesRows(&$rows)
{
    foreach ($rows as $index => $row) {
        if ($row->getColumn('label') === 5) {
            unset($rows[$index]); // remove idSite 5 from totals
        }
    }
}

Callback Signature:

function(&$rows)
  • \Row &$rows An array containing rows, one row for each site. The label columns equals the idSite.

Platform

Platform.initialized

Defined in Piwik/Plugins/Widgetize/tests/System/WidgetTest in line 63

Usages:

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

Platform.initialized

Defined in Piwik/FrontController in line 459

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

Usages:

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

PluginManager

PluginManager.pluginActivated

Defined in Piwik/Plugins/TagManager/tests/Integration/Context/WebContextTest in line 88

Callback Signature:

function('TagManager']

Usages:

CorePluginsAdmin::onPluginActivated, CustomJsTracker::updateTracker, TagManager::onPluginActivated

PluginManager.pluginActivated

Defined in Piwik/Plugin/Manager in line 751

Event triggered after a plugin has been activated.

Callback Signature:

function($pluginName)
  • string $pluginName The plugin that has been activated.

Usages:

CorePluginsAdmin::onPluginActivated, CustomJsTracker::updateTracker, TagManager::onPluginActivated

PluginManager.pluginDeactivated

Defined in Piwik/Plugin/Manager in line 581

Event triggered after a plugin has been deactivated.

Callback Signature:

function($pluginName)
  • string $pluginName The plugin that has been deactivated.

Usages:

CorePluginsAdmin::removePluginChanges, CustomJsTracker::updateTracker, TagManager::onPluginActivateOrInstall

PluginManager.pluginInstalled

Defined in Piwik/Plugin/Manager in line 1417

Event triggered after a new plugin has been installed. Note: Might be triggered more than once if the config file is not writable

Callback Signature:

function($pluginName)
  • string $pluginName The plugin that has been installed.

Usages:

CustomJsTracker::updateTracker, TagManager::onPluginActivateOrInstall

PluginManager.pluginUninstalled

Defined in Piwik/Plugin/Manager in line 670

Event triggered after a plugin has been uninstalled.

Callback Signature:

function($pluginName)
  • string $pluginName The plugin that has been uninstalled.

Usages:

CustomJsTracker::updateTracker, TagManager::onPluginActivateOrInstall

PrivacyManager

PrivacyManager.deleteDataSubjects

Defined in Piwik/Plugins/PrivacyManager/Model/DataSubjects in line 120

Lets you delete data subjects to make your plugin GDPR compliant. This can be useful if you have developed a plugin which stores any data for visits but doesn't use any core logic to store this data. If core API's are used, for example log tables, then the data may be deleted automatically.

Example

public function deleteDataSubjects(&$result, $visitsToDelete)
{
    $numDeletes = $this->deleteVisits($visitsToDelete)
    $result['myplugin'] = $numDeletes;
}

Callback Signature:

function(&$results, $visits]
  • array &$results An array storing the result of how much data was deleted for .

  • array &$visits An array with multiple visit entries containing an idvisit and idsite each. The data for these visits is requested to be deleted.

PrivacyManager.deleteLogsOlderThan

Defined in Piwik/Plugins/PrivacyManager/LogDataPurger in line 104

Triggered when a plugin is supposed to delete log/raw data that is older than a certain amount of days. Example

public function deleteLogsOlderThan($dateUpperLimit, $deleteLogsOlderThan)
{
    Db::query('DELETE FROM mytable WHERE creation_date < ' . $dateUpperLimit->getDateTime());
}

Callback Signature:

function($dateUpperLimit, $deleteLogsOlderThan)
  • Date $dateUpperLimit A date where visits that occur before this time should be deleted.

  • int $deleteLogsOlderThan The number of days after which log entries are considered old. Visits and related data whose age is greater than this number will be purged.

PrivacyManager.exportDataSubjects

Defined in Piwik/Plugins/PrivacyManager/Model/DataSubjects in line 460

Lets you enrich the data export for one or multiple data subjects to make your plugin GDPR compliant. This can be useful if you have developed a plugin which stores any data for visits but doesn't use any core logic to store this data. If core API's are used, for example log tables, then the data may be exported automatically.

Example

public function exportDataSubjects(&export, $visitsToExport)
{
    $export['myplugin'] = array();
    foreach($visitsToExport as $visit) {
         $export['myplugin'][] = 'exported data';
    }
}

Callback Signature:

function(&$results, $visits]
  • array &$results An array containing the exported data subjects.

  • array &$visits An array with multiple visit entries containing an idvisit and idsite each. The data for these visits is requested to be exported.

PrivacyManager.shouldIgnoreDnt

Defined in Piwik/Plugins/PrivacyManager/DoNotTrackHeaderChecker in line 76

Callback Signature:

function(&$shouldIgnore)

Provider

Provider.getCleanHostname

Defined in Piwik/Plugins/Provider/Provider in line 89

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/Plugins/Referrers/SearchEngine in line 65

Callback Signature:

function(&$this->definitionList)

Referrer.addSocialUrls

Defined in Piwik/Plugins/Referrers/Social in line 62

Callback Signature:

function(&$this->definitionList)

Report

Report.addReports

Defined in Piwik/Plugin/ReportsProvider in line 142

Triggered to add new reports that cannot be picked up automatically by the platform. This is useful if the plugin allows a user to create reports / dimensions dynamically. For example CustomDimensions or CustomVariables. There are a variable number of dimensions in this case and it wouldn't be really possible to create a report file for one of these dimensions as it is not known how many Custom Dimensions will exist.

Example

public function addReport(&$reports)
{
    $reports[] = new MyCustomReport();
}

Callback Signature:

function(&$instances)
  • Report $reports An array of reports

Usages:

CustomDimensions::addReports

Report.filterReports

Defined in Piwik/Plugin/ReportsProvider in line 164

Triggered to filter / restrict reports. Example

public function filterReports(&$reports)
{
    foreach ($reports as $index => $report) {
         if ($report->getCategoryId() === 'General_Actions') {
             unset($reports[$index]); // remove all reports having this action
         }
    }
}

Callback Signature:

function(&$instances)
  • Report $reports An array of reports

Usages:

MarketingCampaignsReporting::removeOriginalCampaignReport

Report.unsubscribe

Defined in Piwik/Plugins/ScheduledReports/SubscriptionModel in line 91

Callback Signature:

function($reportfunction('idreport'], $email]

Request

Request.dispatch

Defined in Piwik/Plugins/SitesManager/tests/Integration/SitesManagerTest in line 92

Callback Signature:

function(&$module, &$action, &$params]

Usages:

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

Request.dispatch

Defined in Piwik/Plugins/SitesManager/tests/Integration/SitesManagerTest in line 112

Callback Signature:

function(&$module, &$action, &$params]

Usages:

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

Request.dispatch

Defined in Piwik/Plugins/SitesManager/tests/Integration/SitesManagerTest in line 132

Callback Signature:

function(&$module, &$action, &$params]

Usages:

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

Request.dispatch

Defined in Piwik/Plugins/SitesManager/tests/Integration/SitesManagerTest in line 152

Callback Signature:

function(&$module, &$action, &$params]

Usages:

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

Request.dispatch

Defined in Piwik/Plugins/SitesManager/tests/Integration/SitesManagerTest in line 173

Callback Signature:

function(&$module, &$action, &$params]

Usages:

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

Request.dispatch

Defined in Piwik/FrontController in line 617

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

Request.dispatch.end

Defined in Piwik/Plugins/TwoFactorAuth/tests/System/TwoFactorAuthTest in line 64

Callback Signature:

function(&$html, 'module', 'action', function())

Request.dispatch.end

Defined in Piwik/FrontController in line 662

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 385

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 173

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 string

  • &$action string

Usages:

Referrers::renameDeprecatedModuleAndAction, RssWidget::renameExampleRssWidgetModule, ScheduledReports::renameDeprecatedModuleAndAction

Request.initAuthenticationObject

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

Usages:

Login::onInitAuthenticationObject, LoginLdap::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/Plugins/BulkTracking/Tracker/Handler in line 125

Usages:

Login::onInitAuthenticationObject, LoginLdap::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/Tracker/Request in line 220

Usages:

Login::onInitAuthenticationObject, LoginLdap::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/Console in line 318

Usages:

Login::onInitAuthenticationObject, LoginLdap::initAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/FrontController in line 744

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::onInitAuthenticationObject, LoginLdap::initAuthenticationObject

Request.shouldDisablePostProcessing

Defined in Piwik/API/Request in line 723

After an API method returns a value, the value is post processed (eg, rows are sorted based on the filter_sort_column query parameter, rows are truncated based on the filter_limit/filter_offset parameters, amongst other things). If you're creating a plugin that needs to disable post processing entirely for certain requests, use this event.

Callback Signature:

function(&$shouldDisable, $this->request]
  • bool &$shouldDisable Set this to true to disable datatable post processing for a request.

  • array $request The request parameters.

Usages:

PrivacyManager::shouldDisablePostProcessing

ScheduledReports

ScheduledReports.allowMultipleReports

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

Triggered when we're determining if a scheduled report transport medium can handle sending multiple Matomo 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 Matomo report at a time.

Callback Signature:

function(&$allowMultipleReports, $reportType]
  • bool &$allowMultipleReports Whether the backend type can handle multiple Matomo 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 564

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 1030

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 955

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

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

Callback Signature:

function(&$availableReportMetadata, $reportType, $idSite]
  • array &$availableReportMetadata An array containing 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 774

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 parameter 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 1061

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, $reportfunction('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 1006

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 542

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:

PagePerformance::processReports, ScheduledReports::processReports

ScheduledReports.sendReport

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

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(&$reportType, $report, $contents, $filename = basename($outputFilename), $prettyDate, $reportSubject, $reportTitle, $additionalFiles, \Piwik\Period\Factory::build($reportfunction('period_param'], $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 Matomo 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 801

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

ScheduledTasks

ScheduledTasks.execute

Defined in Piwik/Scheduler/Scheduler in line 349

Triggered directly before a scheduled task is executed

Callback Signature:

function(&$task)
  • Task &$task The task that is about to be executed

ScheduledTasks.execute.end

Defined in Piwik/Scheduler/Scheduler in line 378

Triggered after a scheduled task is successfully executed. You can use the event to execute for example another task whenever a specific task is executed or to clean up certain resources.

Callback Signature:

function(&$task)
  • Task &$task The task that was just executed

ScheduledTasks.shouldExecuteTask

Defined in Piwik/Scheduler/Scheduler in line 165

Triggered before a task is executed. A plugin can listen to it and modify whether a specific task should be executed or not. This way you can force certain tasks to be executed more often or for example to be never executed.

Callback Signature:

function(&$shouldExecuteTask, $task)
  • bool &$shouldExecuteTask Decides whether the task will be executed.

  • Task $task The task that is about to be executed.

Segment

Segment.addSegments

Defined in Piwik/Segment/SegmentsList in line 129

Triggered to add custom segment definitions. Example

public function addSegments(&$segments)
{
    $segment = new Segment();
    $segment->setSegment('my_segment_name');
    $segment->setType(Segment::TYPE_DIMENSION);
    $segment->setName('My Segment Name');
    $segment->setSqlSegment('log_table.my_segment_name');
    $segments[] = $segment;
}

Callback Signature:

function($list)
  • SegmentsList $list An instance of the SegmentsList. You can add segments to the list this way.

Segment.filterSegments

Defined in Piwik/Segment/SegmentsList in line 147

Triggered to filter segment definitions. Example

public function filterSegments(&$segmentList)
{
    $segmentList->remove('Category');
}

Callback Signature:

function($list)

SegmentEditor

SegmentEditor.deactivate

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

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 272

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 103

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 153

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 59

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.

SitesManager

SitesManager.addSite.end

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

Triggered after a site has been added.

Callback Signature:

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

Usages:

TagManager::onSiteAdded

SitesManager.deleteSite.end

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

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, CustomDimensions::deleteCustomDimensionDefinitionsForSite, Goals::deleteSiteGoals, ScheduledReports::deleteSiteReport, SegmentEditor::onDeleteSite, SitesManager::onSiteDeleted, TagManager::onSiteDeleted, UsersManager::deleteSite

SitesManager.getImageTrackingCode

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

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 Matomo installation, eg, 'examplepiwik.com/path/to/piwik'.

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

SitesManager.shouldPerformEmptySiteCheck

Defined in Piwik/Plugins/SitesManager/SitesManager in line 145

Posted before checking to display the "No data has been recorded yet" message. If your Measurable should never have visits, you can use this event to make sure that message is never displayed.

Callback Signature:

function(&$shouldPerformEmptySiteCheck, $siteId]
  • bool &$shouldPerformEmptySiteCheck Set this value to true to perform the check, false if otherwise.

  • int $siteId The ID of the site we would perform a check for.

System

System.addSystemSummaryItems

Defined in Piwik/Plugins/CoreHome/Widgets/GetSystemSummary in line 68

Triggered to add system summary items that are shown in the System Summary widget. Example

public function addSystemSummaryItem(&$systemSummary)
{
    $numUsers = 5;
    $systemSummary[] = new SystemSummary\Item($key = 'users', Piwik::translate('General_NUsers', $numUsers), $value = null, array('module' => 'UsersManager', 'action' => 'index'), $icon = 'icon-user');
}

Callback Signature:

function(&$systemSummary)
  • \Item &$systemSummary An array containing system summary items.

Usages:

CoreAdminHome::addSystemSummaryItems, CorePluginsAdmin::addSystemSummaryItems, Goals::addSystemSummaryItems, SegmentEditor::addSystemSummaryItems, SitesManager::addSystemSummaryItems, TagManager::addSystemSummaryItems, UsersManager::addSystemSummaryItems

System.filterSystemSummaryItems

Defined in Piwik/Plugins/CoreHome/Widgets/GetSystemSummary in line 102

Triggered to filter system summary items that are shown in the System Summary widget. A plugin might also sort the system summary items differently. Example

public function filterSystemSummaryItems(&$systemSummary)
{
    foreach ($systemSummaryItems as $index => $item) {
        if ($item && $item->getKey() === 'users') {
            $systemSummaryItems[$index] = null;
        }
    }
}

Callback Signature:

function(&$systemSummary)
  • \Item &$systemSummary An array containing system summary items.

SystemSettings

SystemSettings.updated

Defined in Piwik/Settings/Plugin/SystemSettings in line 106

Triggered after system settings have been updated. Example

Piwik::addAction('SystemSettings.updated', function (SystemSettings $settings) {
    if ($settings->getPluginName() === 'PluginName') {
        $value = $settings->someSetting->getValue();
        // Do something with the new setting value
    }
});

Callback Signature:

function($this)
  • \Settings $settings The plugin settings object.

TagManager

TagManager.addTags

Defined in Piwik/Plugins/TagManager/Template/Tag/TagsProvider in line 91

Event to add custom tags. To filter tags have a look at the TagManager.filterTags event. Example

public function addTags(&$tags)
{
    $tags[] = new MyCustomTag();
}

Callback Signature:

function(&$tags)
  • BaseTag &$tags An array containing a list of tags.

TagManager.addTriggers

Defined in Piwik/Plugins/TagManager/Template/Trigger/TriggersProvider in line 90

Event to add custom triggers. To filter triggers have a look at the TagManager.filterTriggers event. Example

public function addTriggers(&$triggers)
{
    $triggers[] = new MyCustomTrigger();
}

Callback Signature:

function(&$triggers)
  • BaseTrigger &$triggers An array containing a list of triggers.

TagManager.addVariables

Defined in Piwik/Plugins/TagManager/Template/Variable/VariablesProvider in line 106

Event to add custom variables. To filter variables have a look at the TagManager.filterVariables event. Example

public function addVariables(&$variables)
{
    $variables[] = new MyCustomVariable();
}

Callback Signature:

function(&$variables)
  • BaseVariable &$variables An array containing a list of variables.

TagManager.containerFileChanged

Defined in Piwik/Plugins/TagManager/Context/Storage/Filesystem in line 33

Triggered so plugins can detect the changed file and for example sync it to other servers.

Callback Signature:

function($name)

TagManager.containerFileDeleted

Defined in Piwik/Plugins/TagManager/Context/Storage/Filesystem in line 44

Triggered so plugins can detect the deleted file and for example sync it to other servers.

Callback Signature:

function($name)

TagManager.deleteContainer.end

Defined in Piwik/Plugins/TagManager/API in line 1159

Callback Signature:

function(function('idSite' => $idSite, 'idContainer' => $idContainer))

TagManager.deleteContainerTag.end

Defined in Piwik/Plugins/TagManager/API in line 548

Callback Signature:

function(function('idSite' => $idSite, 'idContainer' => $idContainer, 'idContainerVersion' => $idContainerVersion, 'idTag' => $idTag))

TagManager.deleteContainerTrigger.end

Defined in Piwik/Plugins/TagManager/API in line 705

Callback Signature:

function(function('idSite' => $idSite, 'idContainer' => $idContainer, 'idContainerVersion' => $idContainerVersion, 'idTrigger' => $idTrigger))

TagManager.deleteContainerVariable.end

Defined in Piwik/Plugins/TagManager/API in line 943

Callback Signature:

function(function('idSite' => $idSite, 'idContainer' => $idContainer, 'idContainerVersion' => $idContainerVersion, 'idVariable' => $idVariable))

TagManager.deleteContainerVersion.end

Defined in Piwik/Plugins/TagManager/API in line 1114

Callback Signature:

function(function('idSite' => $idSite, 'idContainer' => $idContainer, 'idContainerVersion' => $idContainerVersion))

TagManager.filterTags

Defined in Piwik/Plugins/TagManager/Template/Tag/TagsProvider in line 124

Triggered to filter / restrict tags. Example

public function filterTags(&$tags)
{
    foreach ($tags as $index => $tag) {
         if ($tag->getId() === 'CustomHtml') {}
             unset($tags[$index]); // remove the tag having this ID
         }
    }
}

Callback Signature:

function(&$tags)
  • BaseTag &$tags An array containing a list of tags.

TagManager.filterTriggers

Defined in Piwik/Plugins/TagManager/Template/Trigger/TriggersProvider in line 123

Event to filter / restrict triggers. Example

public function filterTriggers(&$triggers)
{
    foreach ($triggers as $index => $trigger) {
         if ($trigger->getId() === 'CustomJs') {}
             unset($triggers[$index]); // remove the trigger having this ID
         }
    }
}

Callback Signature:

function(&$triggers)
  • BaseTrigger &$triggers An array containing a list of triggers.

TagManager.filterVariables

Defined in Piwik/Plugins/TagManager/Template/Variable/VariablesProvider in line 140

Event to filter / restrict variables. Example

public function filterVariables(&$variables)
{
    foreach ($variables as $index => $variable) {
         if ($variable->getId() === 'CustomVariable') {}
             unset($variables[$index]); // remove the variable having this ID
         }
    }
}

Callback Signature:

function(&$variables)
  • BaseVariable &$variables An array containing a list of variables.

TagManager.regenerateContainerReleases

Defined in Piwik/Plugins/TagManager/Commands/RegenerateContainers in line 31

Callback Signature:

function($onlyPreview]

Usages:

TagManager::regenerateReleasedContainers

Template

Template.afterCustomVariablesReport

Defined in Piwik/Plugins/CustomVariables/Reports/GetCustomVariables in line 68

Callback Signature:

function(&$out)

Usages:

ProfessionalServices::getCustomVariablesPromo

Template.afterGDPROverviewIntro

Defined in Piwik/Plugins/PrivacyManager/Controller in line 129

Callback Signature:

function(&$afterGDPROverviewIntroContent]

Template.afterReferrerTypeReport

Defined in Piwik/Plugins/Referrers/Reports/GetReferrerType in line 130

Callback Signature:

function(&$out)

Usages:

ProfessionalServices::getReferrerTypePromo

Template.beforeGoalListActionsBody

Defined in Piwik/Plugins/Goals/Controller in line 154

Callback Signature:

function(&$str, $goal]

Template.beforeGoalListActionsHead

Defined in Piwik/Plugins/Goals/Controller in line 163

Callback Signature:

function(&$str]

Template.endGoalEditTable

Defined in Piwik/Plugins/Goals/Controller in line 169

Callback Signature:

function(&$str]

Template.jsGlobalVariables

Defined in Piwik/Plugins/AnonymousPiwikUsageMeasurement/tests/Integration/AnonymousPiwikUsageMeasurementTest in line 75

Callback Signature:

function(&$out)

Usages:

Plugin::getJsGlobalVariables, AnonymousPiwikUsageMeasurement::addMatomoClientTracking, CoreAdminHome::addJsGlobalVariables, LanguagesManager::jsGlobalVariables, Live::addJsGlobalVariables, Transitions::addJsGlobalVariables

Template.jsGlobalVariables

Defined in Piwik/Plugins/AnonymousPiwikUsageMeasurement/tests/Integration/AnonymousPiwikUsageMeasurementTest in line 90

Callback Signature:

function(&$out)

Usages:

Plugin::getJsGlobalVariables, AnonymousPiwikUsageMeasurement::addMatomoClientTracking, CoreAdminHome::addJsGlobalVariables, LanguagesManager::jsGlobalVariables, Live::addJsGlobalVariables, Transitions::addJsGlobalVariables

Template.jsGlobalVariables

Defined in Piwik/Plugins/AnonymousPiwikUsageMeasurement/tests/Integration/AnonymousPiwikUsageMeasurementTest in line 103

Callback Signature:

function(&$out)

Usages:

Plugin::getJsGlobalVariables, AnonymousPiwikUsageMeasurement::addMatomoClientTracking, CoreAdminHome::addJsGlobalVariables, LanguagesManager::jsGlobalVariables, Live::addJsGlobalVariables, Transitions::addJsGlobalVariables

Template.jsGlobalVariables

Defined in Piwik/Plugins/AnonymousPiwikUsageMeasurement/tests/Integration/AnonymousPiwikUsageMeasurementTest in line 120

Callback Signature:

function(&$out)

Usages:

Plugin::getJsGlobalVariables, AnonymousPiwikUsageMeasurement::addMatomoClientTracking, CoreAdminHome::addJsGlobalVariables, LanguagesManager::jsGlobalVariables, Live::addJsGlobalVariables, Transitions::addJsGlobalVariables

Template.siteWithoutDataTab. . $obj::getId() . .content

Defined in Piwik/Plugins/SitesManager/Controller in line 164

Event that can be used to manipulate the content of a certain tab on the no data page

Callback Signature:

function(&$tabContent, $this->siteContentDetector]
  • string &$tabContent Content of the tab

  • \SiteContentDetector $detector Instance of SiteContentDetector, holding current detection results

Template.siteWithoutDataTab. . $obj::getId() . .others

Defined in Piwik/Plugins/SitesManager/Controller in line 171

Event that can be used to manipulate the content of a record on the others tab on the no data page

Callback Signature:

function(&$othersInstruction, $this->siteContentDetector]
  • string &$othersInstruction Content of the record

  • \SiteContentDetector $detector Instance of SiteContentDetector, holding current detection results

Tour

Tour.filterChallenges

Defined in Piwik/Plugins/Tour/Engagement/Challenges in line 114

Triggered to add new challenges to the "welcome to Matomo tour". Example

public function addChallenge(&$challenges)
{
    $challenges[] = new MyChallenge();
}

Callback Signature:

function(&$challenges)
  • Challenge &$challenges An array of challenges

Tracker

Tracker.Cache.getSiteAttributes

Defined in Piwik/Tracker/Cache in line 131

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:

CustomDimensions::addCustomDimensionsAttributes, Goals::fetchGoalsFromDb, UsersManager::recordAdminUsersInCache

Tracker.detectReferrerSearchEngine

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

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 Matomo's default search engine detection
                                   logic.
    
  • string referrerUrl The referrer URL from the tracking request.

Tracker.detectReferrerSocialNetwork

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

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

Callback Signature:

function(&$socialNetworkName, $this->referrerUrl]
  • string &$socialNetworkName Name of the social network, or false if none detected

                                   This parameter is initialized to the results
                                   of Matomo's default social network detection
                                   logic.
    
  • string referrerUrl The referrer URL from the tracking request.

Tracker.end

Defined in Piwik/Plugins/QueuedTracking/Commands/Process in line 94

Tracker.end

Defined in Piwik/Tracker in line 134

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 Matomo 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.getJavascriptCode

Defined in Piwik/Tracker/TrackerCodeGenerator in line 227

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**: Matomo url protocol.
                    - **loadAsync**: boolean whether piwik.js should be loaded synchronous or asynchronous
    
                    The **httpsPiwikUrl** element can be set if the HTTPS
                    domain is different from the normal domain.
    
  • array $parameters The parameters supplied to TrackerCodeGenerator::generate().

Tracker.isExcludedVisit

Defined in Piwik/Tracker/VisitExcluded in line 102

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, $this->request)
  • 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.

  • \Request $request The request object which contains all of the request's information

Usages:

JsTrackerInstallCheck::isExcludedVisit, TrackingSpamPrevention::isExcludedVisit

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 Matomo uses the default class.

Tracker.PageUrl.getQueryParametersToExclude

Defined in Piwik/Tracker/PageUrl in line 102

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.

Usages:

MarketingCampaignsReporting::getQueryParametersToExclude, TagManager::getQueryParametersToExclude

Tracker.Request.getIdSite

Defined in Piwik/Tracker/Request in line 591

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 212

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

CoreHome::setTrackerCacheGeneral, CustomDimensions::setTrackerCacheGeneral, CustomVariables::getCacheGeneral, PrivacyManager::setTrackerCacheGeneral, Referrers::setTrackerCacheGeneral, SitesManager::setTrackerCacheGeneral, TrackingSpamPrevention::setTrackerCacheGeneral, UserCountry::setTrackerCacheGeneral

TrackingSpamPrevention

TrackingSpamPrevention.banIp

Defined in Piwik/Plugins/TrackingSpamPrevention/BlockedIpRanges in line 152

This event is posted when an IP is being banned from tracking. You can use it for example to notify someone that this IP was banned.

Callback Signature:

function($ipRange, $ip]
  • string $ipRange The IP range that will be blocked

  • string $ip The IP that caused this range to be blocked

Usages:

TrackingSpamPrevention::onBanIp

Translate

Translate.getClientSideTranslationKeys

Defined in Piwik/Translation/Translator in line 263

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:

Plugin::getClientSideTranslationKeys, Annotations::getClientSideTranslationKeys, CoreAdminHome::getClientSideTranslationKeys, CoreHome::getClientSideTranslationKeys, CorePluginsAdmin::getClientSideTranslationKeys, CoreVisualizations::getClientSideTranslationKeys, CustomAlerts::getClientSideTranslationKeys, CustomDimensions::getClientSideTranslationKeys, CustomVariables::getClientSideTranslationKeys, DBStats::getClientSideTranslationKeys, Dashboard::getClientSideTranslationKeys, DevicesDetection::getClientSideTranslationKeys, Diagnostics::getClientSideTranslationKeys, Ecommerce::getClientSideTranslationKeys, Feedback::getClientSideTranslationKeys, GeoIp2::getClientSideTranslationKeys, Goals::getClientSideTranslationKeys, Installation::getClientSideTranslationKeys, Intl::getClientSideTranslationKeys, JsTrackerInstallCheck::getClientSideTranslationKeys, LanguagesManager::getClientSideTranslationKeys, Live::getClientSideTranslationKeys, LogViewer::getClientSideTranslationKeys, Login::getClientSideTranslationKeys, LoginLdap::getClientSideTranslationKeys, Marketplace::getClientSideTranslationKeys, MobileMessaging::getClientSideTranslationKeys, MultiSites::getClientSideTranslationKeys, Overlay::getClientSideTranslationKeys, PagePerformance::getClientSideTranslationKeys, PrivacyManager::getClientSideTranslationKeys, ProfessionalServices::getClientSideTranslationKeys, Referrers::getClientSideTranslationKeys, ScheduledReports::getClientSideTranslationKeys, SecurityInfo::getClientSideTranslationKeys, SegmentEditor::getClientSideTranslationKeys, SitesManager::getClientSideTranslationKeys, TagManager::getClientSideTranslationKeys, TasksTimetable::getClientSideTranslationKeys, Transitions::getClientSideTranslationKeys, TwoFactorAuth::getClientSideTranslationKeys, UserCountry::getClientSideTranslationKeys, UserCountryMap::getClientSideTranslationKeys, UserId::getClientSideTranslationKeys, UsersManager::getClientSideTranslationKeys, VisitorGenerator::getClientSideTranslationKeys, Widgetize::getClientSideTranslationKeys

TwoFactorAuth

TwoFactorAuth.disabled

Defined in Piwik/Plugins/TwoFactorAuth/TwoFactorAuthentication in line 70

Callback Signature:

function($login)

TwoFactorAuth.enabled

Defined in Piwik/Plugins/TwoFactorAuth/Controller in line 226

Callback Signature:

function($login)

TwoFactorAuth.requiresTwoFactorAuthentication

Defined in Piwik/Plugins/TwoFactorAuth/TwoFactorAuth in line 261

Callback Signature:

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

Usages:

TagManager::requiresTwoFactorAuthentication

Updater

Updater.componentInstalled

Defined in Piwik/Updater in line 111

Event triggered after a new component has been installed.

Callback Signature:

function($name)
  • string $name The component that has been installed.

Updater.componentUninstalled

Defined in Piwik/Updater in line 161

Event triggered after a component has been uninstalled.

Callback Signature:

function($name)
  • string $name The component that has been uninstalled.

Updater.componentUpdated

Defined in Piwik/Updater in line 139

Event triggered after a component has been updated. Can be used to handle logic that should be done after a component was updated

Example

Piwik::addAction('Updater.componentUpdated', function ($componentName, $updatedVersion) {
     $mail = new Mail();
     $mail->setDefaultFromPiwik();
     $mail->addTo('test@example.org');
     $mail->setSubject('Component was updated);
     $message = sprintf(
         'Component %1$s has been updated to version %2$s',
         $componentName, $updatedVersion
     );
     $mail->setBodyText($message);
     $mail->send();
});

Callback Signature:

function($name, $version)
  • string $componentName 'core', plugin name or dimension name

  • string $updatedVersion version updated to

Usages:

CorePluginsAdmin::addPluginChanges, CustomJsTracker::updateTracker, TagManager::regenerateReleasedContainers

User

User.isNotAuthorized

Defined in Piwik/FrontController in line 182

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, LoginLdap::noAccess

UserSettings

UserSettings.updated

Defined in Piwik/Settings/Plugin/UserSettings in line 89

Triggered after user settings have been updated. Example

Piwik::addAction('UserSettings.updated', function (UserSettings $settings) {
    if ($settings->getPluginName() === 'PluginName') {
        $value = $settings->someSetting->getValue();
        // Do something with the new setting value
    }
});

Callback Signature:

function($this)
  • \Settings $settings The plugin settings object.

UsersManager

UsersManager.addUser.end

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

Triggered after a new user is created.

Callback Signature:

function($userLogin, $email, Piwik::getCurrentUserLogin()]
  • string $userLogin The new user's login.

  • string $email The new user's e-mail.

  • string $inviterLogin The login of the user who created the new user

UsersManager.checkPassword

Defined in Piwik/Plugins/UsersManager/UsersManager in line 181

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.

Usages:

LoginLdap::checkPassword

UsersManager.deleteUser

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

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 $userLogins The login handle of the deleted user.

Usages:

CoreAdminHome::cleanupUser, CoreVisualizations::deleteUser, CustomAlerts::deleteAlertsForLogin, Dashboard::deleteDashboardLayout, LanguagesManager::deleteUserLanguage, LoginLdap::onUserDeleted, ScheduledReports::deleteUserReport, SegmentEditor::onDeleteUser

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.inviteUser.accepted

Defined in Piwik/Plugins/Login/Controller in line 640

Triggered after a user accepted an invite

Callback Signature:

function($userfunction('login'], $userfunction('email'], $userfunction('invited_by']]
  • string $userLogin The invited user's login.

  • string $email The invited user's e-mail.

  • string $inviterLogin The login of the user, who invited this user

UsersManager.inviteUser.declined

Defined in Piwik/Plugins/Login/Controller in line 710

Triggered after a user accepted an invite

Callback Signature:

function($userfunction('login'], $userfunction('email'], $userfunction('invited_by']]
  • string $userLogin The invited user's login.

  • string $email The invited user's e-mail.

  • string $inviterLogin The login of the user, who invited this user

UsersManager.inviteUser.end

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

Triggered after a new user was invited.

Callback Signature:

function($userLogin, $email]
  • string $userLogin The new user's login.

  • string $email The new user's e-mail.

Usages:

Tour::onUserInvited

UsersManager.inviteUser.generateInviteLinkToken

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

Triggered after a new user invite token was generate.

Callback Signature:

function($userLogin, $userfunction('email']]
  • string $userLogin The new user's login.

UsersManager.inviteUser.resendInvite

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

Triggered after a new user was invited.

Callback Signature:

function($userLogin, $userfunction('email']]
  • string $userLogin The new user's login.

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 1155

Callback Signature:

function($userLogin, $idSites]

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.updateUser.end

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

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

Callback Signature:

function($userLogin, $passwordHasBeenUpdated, $email, $password]
  • string $userLogin The user's login handle.

  • boolean $passwordHasBeenUpdated Flag containing information about password change.

ViewDataTable

ViewDataTable.configure

Defined in Piwik/Plugin/ViewDataTable in line 274

Triggered during ViewDataTable construction. Subscribers should customize the view based on the report that is being displayed. This event is triggered before view configuration properties are overwritten by saved settings or request parameters. Use this to define default values.

Plugins that define their own reports must subscribe to this event in order to specify how the Matomo 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, Bandwidth::configureViewDataTable, Events::configureViewDataTable, PagePerformance::configureViewDataTable

ViewDataTable.configure.end

Defined in Piwik/Plugin/ViewDataTable in line 316

Triggered after ViewDataTable construction. Subscribers should customize the view based on the report that is being displayed. This event is triggered after all view configuration values have been overwritten by saved settings or request parameters. Use this if you need to work with the final configuration values.

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

Example

// event handler
public function configureViewDataTableEnd(ViewDataTable $view)
{
    if ($view->requestConfig->apiMethodToRequestDataTable == 'VisitTime.getVisitInformationPerServerTime'
        && $view->requestConfig->flat == 1) {
            $view->config->show_header_message = 'You are viewing this report flattened';
    }
}

Callback Signature:

function($this)

ViewDataTable.filterViewDataTable

Defined in Piwik/ViewDataTable/Manager in line 117

Triggered to filter available DataTable visualizations. Plugins that want to disable certain visualizations should subscribe to this event and remove visualizations from the incoming array.

Example

public function filterViewDataTable(&$visualizations)
{
    unset($visualizations[HtmlTable::ID]);
}

Callback Signature:

function(&$result)
  • array &$visualizations An array of all available visualizations indexed by visualization ID.

Usages:

TreemapVisualization::removeTreemapVisualizationIfFlattenIsUsed

Visualization

Visualization.beforeRender

Defined in Piwik/Plugin/Visualization in line 822

Posted immediately before rendering the view. Plugins can use this event to perform last minute configuration of the view based on it's data or the report being viewed.

Callback Signature:

function($this]

Usages:

PrivacyManager::onConfigureVisualisation

Widget

Widget.addWidgetConfigs

Defined in Piwik/Plugin/WidgetsProvider in line 62

Triggered to add custom widget configs. To filter widgets have a look at the Widget.filterWidgets event. Example

public function addWidgetConfigs(&$configs)
{
    $config = new WidgetConfig();
    $config->setModule('PluginName');
    $config->setAction('renderDashboard');
    $config->setCategoryId('Dashboard_Dashboard');
    $config->setSubcategoryId('dashboardId');
    $configs[] = $config;
}

Callback Signature:

function(&$configs)
  • array &$configs An array containing a list of widget config entries.

Usages:

Dashboard::addWidgetConfigs

Widget.filterWidgets

Defined in Piwik/Widget/WidgetsList in line 214

Triggered to filter widgets. Example

public function removeWidgetConfigs(Piwik\Widget\WidgetsList $list)
{
    $list->remove($category='General_Visits'); // remove all widgets having this category
}

Callback Signature:

function($list)
  • WidgetsList $list An instance of the WidgetsList. You can change the list of widgets this way.

Usages:

Marketplace::filterWidgets, RssWidget::filterWidgets, SEO::filterWidgets

Widgetize

Widgetize.shouldEmbedIframeEmpty

Defined in Piwik/Plugins/Widgetize/Controller in line 79

Triggered to detect whether a widgetized report should be wrapped in the widgetized HTML or whether only the rendered output of the controller/action should be printed. Set $shouldEmbedEmpty to true if your widget renders the full HTML itself. Example

public function embedIframeEmpty(&$shouldEmbedEmpty, $controllerName, $actionName)
{
    if ($controllerName == 'Dashboard' && $actionName == 'index') {
        $shouldEmbedEmpty = true;
    }
}

Callback Signature:

function(&$shouldEmbedEmpty, $controllerName, $actionName)
  • string &$shouldEmbedEmpty Defines whether the iframe should be embedded empty or wrapped within the widgetized html.

  • string $controllerName The name of the controller that will be executed.

  • string $actionName The name of the action within the controller that will be executed.

Usages:

Dashboard::shouldEmbedIframeEmpty