Events

Events

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

Access

Access.Capability.addCapabilities

Defined in Piwik/Access/CapabilitiesProvider in line 42

Triggered to add new capabilities. Example

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

Callback Signature:

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

Access.Capability.filterCapabilities

Defined in Piwik/Access/CapabilitiesProvider in line 61

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 274

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 91

Callback Signature:

function(&$metricsConfig)

Actions.getCustomActionDimensionFieldsAndJoins

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

Callback Signature:

function(&$customFields, &$customJoins)

Usages:

Contents::provideActionDimensionFields, CustomVariables::provideActionDimensionFields, Events::provideActionDimensionFields

API

API.$pluginName.$methodName

Defined in Piwik/API/Proxy in line 205

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 280

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 180

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.

API.DocumentationGenerator.$token

Defined in Piwik/API/Proxy in line 518

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

Callback Signature:

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

API.getReportMetadata.end

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

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 431

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

Callback Signature:

function($tokenAuth)
  • string $token_auth The value of the token_auth query parameter.

Usages:

Login::ApiRequestAuthenticate

API.Request.authenticate.failed

Defined in Piwik/API/Request in line 437

Usages:

Login::onFailedLoginRecordAttempt

API.Request.dispatch

Defined in Piwik/API/Proxy in line 185

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

Example

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

Callback Signature:

function(&$finalParameters, $pluginName, $methodName)
  • array &$finalParameters List of parameters that will be passed to the API method.

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

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

Usages:

CustomAlerts::checkApiPermission

API.Request.dispatch.end

Defined in Piwik/API/Proxy in line 320

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.

API.Request.intercept

Defined in Piwik/API/Proxy in line 220

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.Parameters.getIdSites

Defined in Piwik/ArchiveProcessor/Parameters in line 132

Callback Signature:

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

ArchiveProcessor.shouldAggregateFromRawData

Defined in Piwik/ArchiveProcessor/PluginsArchiver in line 87

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

Archiving

Archiving.getIdSitesToArchiveWhenNoVisits

Defined in Piwik/ArchiveProcessor/Loader in line 253

Callback Signature:

function(&$idSites)

Archiving.getIdSitesToMarkArchivesAsInvalidated

Defined in Piwik/Archive/ArchiveInvalidator in line 177

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)
  • array &$idSites An array containing a list of site IDs which are requested to be invalidated.

Archiving.makeNewArchiverObject

Defined in Piwik/ArchiveProcessor/PluginsArchiver in line 316

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, $this->isTemporaryArchive)
  • 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 $this->isTemporaryArchive Flag indicating whether the archive being processed is temporary (ie. the period isn't finished yet) or final (the period is already finished and in the past).

AssetManager

AssetManager.addStylesheets

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

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 69

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 140

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

Callback Signature:

function(&$mergedContent)
  • string &$mergedContent The merged and minified CSS.

AssetManager.getJavaScriptFiles

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

Triggered when gathering the list of all JavaScript files needed by 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, Contents::getJsFiles, CoreAdminHome::getJsFiles, CoreHome::getJsFiles, CorePluginsAdmin::getJsFiles, CoreVisualizations::getJsFiles, CustomAlerts::getJavaScriptFiles, CustomVariables::getJsFiles, Dashboard::getJsFiles, Feedback::getJsFiles, Goals::getJsFiles, Insights::getJsFiles, LanguagesManager::getJsFiles, Live::getJsFiles, Login::getJsFiles, Marketplace::getJsFiles, MobileMessaging::getJsFiles, MultiSites::getJsFiles, Overlay::getJsFiles, PrivacyManager::getJsFiles, Referrers::getJsFiles, ScheduledReports::getJsFiles, SegmentEditor::getJsFiles, SitesManager::getJsFiles, Transitions::getJsFiles, TreemapVisualization::getJsFiles, TwoFactorAuth::getJsFiles, UserCountry::getJsFiles, UserCountryMap::getJsFiles, UserId::getJavaScriptFiles, UsersManager::getJsFiles, Widgetize::getJsFiles

AssetManager.getStylesheetFiles

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

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, CustomVariables::getStylesheetFiles, Dashboard::getStylesheetFiles, Diagnostics::getStylesheetFiles, Events::getStylesheetFiles, Feedback::getStylesheetFiles, Goals::getStylesheetFiles, Insights::getStylesheetFiles, Installation::getStylesheetFiles, Live::getStylesheetFiles, Login::getStylesheetFiles, Marketplace::getStylesheetFiles, MobileMessaging::getStylesheetFiles, MultiSites::getStylesheetFiles, PrivacyManager::getStylesheetFiles, ProfessionalServices::getStylesheetFiles, Referrers::getStylesheetFiles, RssWidget::getStylesheetFiles, ScheduledReports::getStylesheetFiles, SecurityInfo::getStylesheetFiles, SegmentEditor::getStylesheetFiles, SitesManager::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:

Dashboard::addSubcategories, Goals::addSubcategories

Config

Config.badConfigurationFile

Defined in Piwik/FrontController in line 334

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

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

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 156

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 562

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 579

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 346

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 402

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.

CoreAdminHome

CoreAdminHome.customLogoChanged

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

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 498

Triggered after Matomo has been updated.

Usages:

CustomPiwikJs::updateTracker

CronArchive

CronArchive.archiveSingleSite.finish

Defined in Piwik/CronArchive in line 498

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

Callback Signature:

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

CronArchive.archiveSingleSite.start

Defined in Piwik/CronArchive in line 488

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

Callback Signature:

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

CronArchive.end

Defined in Piwik/CronArchive in line 550

This event is triggered after archiving.

Callback Signature:

function($this)
  • CronArchive $this

Usages:

CustomPiwikJs::updateTracker

CronArchive.filterWebsiteIds

Defined in Piwik/CronArchive in line 1168

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

Callback Signature:

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

CronArchive.getIdSitesNotUsingTracker

Defined in Piwik/CronArchive in line 1567

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(&$this->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 371

This event is triggered after a CronArchive instance is initialized.

Callback Signature:

function($this->websites->getInitialSiteIds())
  • array $websiteIds The list of website IDs this CronArchive instance is processing. This will be the entire list of IDs regardless of whether some have already been processed.

CronArchive.init.start

Defined in Piwik/CronArchive in line 329

This event is triggered during initializing archiving.

Callback Signature:

function($this)
  • CronArchive $this

CustomMatomoJs

CustomMatomoJs.manipulateJsTracker

Defined in Piwik/Plugins/CustomPiwikJs/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

CustomPiwikJs

CustomPiwikJs.piwikJsChanged

Defined in Piwik/Plugins/CustomPiwikJs/TrackerUpdater in line 141

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

Callback Signature:

function($this->toFile->getPath())
  • string $absolutePath The path to the new piwik.js file.

CustomPiwikJs.piwikJsChanged

Defined in Piwik/Plugins/CustomPiwikJs/TrackerUpdater in line 156

Callback Signature:

function($file->getPath())

CustomPiwikJs.shouldAddTrackerFile

Defined in Piwik/Plugins/CustomPiwikJs/TrackingCode/PluginTrackerFiles in line 95

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

Dashboard

Dashboard.changeDefaultDashboardLayout

Defined in Piwik/Plugins/Dashboard/Dashboard in line 191

Allows other plugins to modify the default dashboard layout.

Callback Signature:

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

Db

Db.cannotConnectToDb

Defined in Piwik/FrontController in line 311

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 91

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 92

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

Dimension

Dimension.addDimensions

Defined in Piwik/Columns/Dimension in line 773

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:

CustomVariables::addDimensions

Dimension.filterDimensions

Defined in Piwik/Columns/Dimension in line 797

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 98

Filesystem

Filesystem.allCachesCleared

Defined in Piwik/Filesystem in line 45

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

FrontController

FrontController.modifyErrorPage

Defined in Piwik/ExceptionHandler in line 133

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.

Goals

Goals.getReportsWithGoalMetrics

Defined in Piwik/Plugins/Goals/Goals in line 320

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

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

Example

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

Callback Signature:

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

Insights

Insights.addReportToOverview

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

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

Example

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

Callback Signature:

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

Usages:

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

Installation

Installation.defaultSettingsForm.init

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

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:

PrivacyManager::installationFormInit

Installation.defaultSettingsForm.submit

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

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:

PrivacyManager::installationFormSubmit

LanguageManager

LanguageManager.getAvailableLanguages

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

Hook called after loading available language files. Use this hook to customise the list of languagesPath available in 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 93

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 182

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 121

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

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

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

Example

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

Callback Signature:

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

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

Live.getExtraVisitorDetails

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

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

This event is deprecated, use VisitorDetails classes instead.

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

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

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

Callback Signature:

function(&$result)
  • array $visitorProfile The unaugmented visitor profile info.

Live.makeNewVisitorObject

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

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

Callback Signature:

function(&$visitor, $visitorRawData)
  • \Piwik\Plugins\Live\VisitorInterface &$visitor Initialized to null, but can be set to a new visitor object. If it isn't modified 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 135

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 113

Callback Signature:

function($auth->getLogin())

Usages:

Login::onFailedLoginRecordAttempt

Login.authenticate.failed

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

Callback Signature:

function($userLogin)

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 118

Callback Signature:

function($auth->getLogin())

Usages:

Login::beforeLoginCheckBruteForce

Login.beforeLoginCheckAllowed

Defined in Piwik/Plugins/Login/PasswordVerifier in line 47

Usages:

Login::beforeLoginCheckBruteForce

Login.logout

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

Callback Signature:

function(Piwik::getCurrentUserLogin())

Login.recordFailedLoginAttempt

Defined in Piwik/Plugins/Login/PasswordVerifier in line 65

Usages:

Login::onFailedLoginRecordAttempt

Mail

Mail.send

Defined in Piwik/Mail in line 147

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 $this The Mail instance that is about to be sent.

Mail.shouldSend

Defined in Piwik/Mail in line 226

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 139

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 142

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 118

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 156

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 431

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

Defined in Piwik/Metrics in line 319

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

Callback Signature:

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

Usages:

Actions::addMetricTranslations, Contents::addMetricTranslations, DevicePlugins::addMetricTranslations, Events::addMetricTranslations, Goals::addMetricTranslations, MultiSites::addMetricTranslations, VisitFrequency::addMetricTranslations

Metrics.getEvolutionUnit

Defined in Piwik/Metrics in line 253

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

MobileMessaging

MobileMessaging.deletePhoneNumber

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

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

Example

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

Callback Signature:

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

Usages:

CustomAlerts::removePhoneNumberFromAllAlerts, ScheduledReports::deletePhoneNumber

MultiSites

MultiSites.filterRowsForTotalsCalculation

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

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.

Piwik

Piwik.getJavascriptCode

Defined in Piwik/Tracker/TrackerCodeGenerator in line 185

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 syncronous 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().

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 399

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/Plugin/Manager in line 521

Event triggered after a plugin has been activated.

Callback Signature:

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

Usages:

CorePluginsAdmin::onPluginActivated, CustomPiwikJs::updateTracker

PluginManager.pluginDeactivated

Defined in Piwik/Plugin/Manager in line 357

Event triggered after a plugin has been deactivated.

Callback Signature:

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

Usages:

CustomPiwikJs::updateTracker

PluginManager.pluginInstalled

Defined in Piwik/Plugin/Manager in line 1180

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:

CustomPiwikJs::updateTracker

PluginManager.pluginUninstalled

Defined in Piwik/Plugin/Manager in line 446

Event triggered after a plugin has been uninstalled.

Callback Signature:

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

Usages:

CustomPiwikJs::updateTracker

PrivacyManager

PrivacyManager.deleteDataSubjects

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

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 95

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 entires 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 347

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.

Provider

Provider.getCleanHostname

Defined in Piwik/Plugins/Provider/Provider in line 94

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 66

Callback Signature:

function(&$this->definitionList)

Referrer.addSocialUrls

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

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

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->getCategory() === 'Actions') {}
             unset($reports[$index]); // remove all reports having this action
         }
    }
}

Callback Signature:

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

Report.unsubscribe

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

Callback Signature:

function($report['idreport'], $email)

Request

Request.dispatch

Defined in Piwik/FrontController in line 544

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/FrontController in line 589

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 349

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:

CoreHome::initAuthenticationObject, CoreUpdater::dispatch, LanguagesManager::initLanguage

Request.getRenamedModuleAndAction

Defined in Piwik/API/Request in line 170

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

Callback Signature:

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

  • $action

Usages:

ProfessionalServices::renameProfessionalServicesModule, Referrers::renameDeprecatedModuleAndAction, RssWidget::renameExampleRssWidgetModule, ScheduledReports::renameDeprecatedModuleAndAction

Request.initAuthenticationObject

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

Usages:

CoreHome::initAuthenticationObject, Login::onInitAuthenticationObject

Request.initAuthenticationObject

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

Usages:

CoreHome::initAuthenticationObject, Login::onInitAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/Tracker/Request in line 193

Usages:

CoreHome::initAuthenticationObject, Login::onInitAuthenticationObject

Request.initAuthenticationObject

Defined in Piwik/FrontController in line 656

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:

CoreHome::initAuthenticationObject, Login::onInitAuthenticationObject

Request.shouldDisablePostProcessing

Defined in Piwik/API/Request in line 634

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.

ScheduledReports

ScheduledReports.allowMultipleReports

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

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 501

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 Matomo\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 947

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 872

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 708

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

Callback Signature:

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

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

Usages:

MobileMessaging::getReportParameters, ScheduledReports::getReportParameters

ScheduledReports.getReportRecipients

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

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

Callback Signature:

function(&$recipients, $report['type'], $report)
  • array &$recipients An array of strings describing each of the scheduled reports recipients. Can be, for example, a list of email addresses or phone numbers or whatever else your plugin uses.

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

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

Usages:

MobileMessaging::getReportRecipients, ScheduledReports::getReportRecipients

ScheduledReports.getReportTypes

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

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 479

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

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

Callback Signature:

function(&$processedReports, $reportType, $outputType, $report)
  • array &$processedReports The list of processed reports in the scheduled report. Entries includes report data and metadata for each report.

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

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

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

Usages:

ScheduledReports::processReports

ScheduledReports.sendReport

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

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

Callback Signature:

function($report['type'], $report, $contents, $filename = basename($outputFilename), $prettyDate, $reportSubject, $reportTitle, $additionalFiles, \Piwik\Period\Factory::build($report['period'], $date), $force)
  • string $reportType A string ID describing how the report is sent, eg, 'sms' or 'email'.

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

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

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

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

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

  • string $reportTitle The scheduled report's given title (given by a 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 735

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 242

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 262

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 133

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/Plugins/API/SegmentMetadata in line 45

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(&$segments)
  • array &$segments An array containing a list of segment entries.

SegmentEditor

SegmentEditor.deactivate

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

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 257

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 101

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 151

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 60

Use this event to register new SEO metrics providers.

Callback Signature:

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

SitesManager

SitesManager.addSite.end

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

Triggered after a site has been added.

Callback Signature:

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

SitesManager.deleteSite.end

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

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

Callback Signature:

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

Usages:

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

SitesManager.getImageTrackingCode

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

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 98

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 66

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', Matomo::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, UsersManager::addSystemSummaryItems

System.filterSystemSummaryItems

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

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 108

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.

Template

Template.afterCustomVariablesReport

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

Callback Signature:

function(&$out)

Usages:

ProfessionalServices::getCustomVariablesPromo

Template.afterReferrerTypeReport

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

Callback Signature:

function(&$out)

Usages:

ProfessionalServices::getReferrerTypePromo

Tracker

Tracker.Cache.getSiteAttributes

Defined in Piwik/Tracker/Cache in line 98

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

Example

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

Callback Signature:

function(&$content, $idSite)
  • array &$content Array mapping of site attribute names with values.

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

Usages:

Goals::fetchGoalsFromDb, UsersManager::recordAdminUsersInCache

Tracker.detectReferrerSearchEngine

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

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

Tracker.detectReferrerSocialNetwork

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

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

Tracker.end

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

Tracker.end

Defined in Piwik/Tracker in line 102

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

Defined in Piwik/Tracker/VisitExcluded in line 95

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

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

Defined in Piwik/Tracker/GoalManager in line 713

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

This event is deprecated, use Dimensions instead.

Callback Signature:

function(&$conversion, $visitInformation, $request, $action)
  • array &$conversion The conversion entity. Read this to see what it contains.

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

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

  • Action $action An action object like ActionPageView or ActionDownload, or null if no action is supposed to be processed.

Tracker.PageUrl.getQueryParametersToExclude

Defined in Piwik/Tracker/PageUrl in line 95

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

Callback Signature:

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

Tracker.Request.authenticate.failed

Defined in Piwik/Tracker/Request in line 224

Usages:

Login::onFailedLoginRecordAttempt

Tracker.Request.getIdSite

Defined in Piwik/Tracker/Request in line 545

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

Callback Signature:

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

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

Tracker.setTrackerCacheGeneral

Defined in Piwik/Tracker/Cache in line 162

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

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

Example

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

Callback Signature:

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

Usages:

PrivacyManager::setTrackerCacheGeneral, Referrers::setTrackerCacheGeneral, SitesManager::setTrackerCacheGeneral, UserCountry::setTrackerCacheGeneral

Tracking

Tracking.makeFailuresHumanReadable

Defined in Piwik/Tracker/Failures in line 193

Callback Signature:

function(&$failures)

Translate

Translate.getClientSideTranslationKeys

Defined in Piwik/Translation/Translator in line 167

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

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

Example

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

Callback Signature:

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

Usages:

Annotations::getClientSideTranslationKeys, CoreAdminHome::getClientSideTranslationKeys, CoreHome::getClientSideTranslationKeys, CorePluginsAdmin::getClientSideTranslationKeys, CoreVisualizations::getClientSideTranslationKeys, CustomAlerts::getClientSideTranslationKeys, CustomVariables::getClientSideTranslationKeys, Dashboard::getClientSideTranslationKeys, Feedback::getClientSideTranslationKeys, Goals::getClientSideTranslationKeys, Live::getClientSideTranslationKeys, Marketplace::getClientSideTranslationKeys, MobileMessaging::getClientSideTranslationKeys, MultiSites::getClientSideTranslationKeys, Overlay::getClientSideTranslationKeys, PrivacyManager::getClientSideTranslationKeys, Referrers::getClientSideTranslationKeys, ScheduledReports::getClientSideTranslationKeys, SegmentEditor::getClientSideTranslationKeys, SitesManager::getClientSideTranslationKeys, Transitions::getClientSideTranslationKeys, UserCountry::getClientSideTranslationKeys, UserCountryMap::getClientSideTranslationKeys, UserId::getClientSideTranslationKeys, UsersManager::getClientSideTranslationKeys, Widgetize::getClientSideTranslationKeys

TwoFactorAuth

TwoFactorAuth.disabled

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

Callback Signature:

function($login)

TwoFactorAuth.enabled

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

Callback Signature:

function($login)

TwoFactorAuth.requiresTwoFactorAuthentication

Defined in Piwik/Plugins/TwoFactorAuth/TwoFactorAuth in line 172

Callback Signature:

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

Updater

Updater.componentInstalled

Defined in Piwik/Updater in line 104

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 154

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 132

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:

CustomPiwikJs::updateTracker

User

User.isNotAuthorized

Defined in Piwik/FrontController in line 165

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

UserSettings

UserSettings.updated

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

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 687

Triggered after a new user is created.

Callback Signature:

function($userLogin, $email, $password, $alias)
  • string $userLogin The new user's login handle.

UsersManager.checkPassword

Defined in Piwik/Plugins/UsersManager/UsersManager in line 188

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

Example

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

Callback Signature:

function($password)
  • string $password Checking password in plain text.

UsersManager.deleteUser

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

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, ScheduledReports::deleteUserReport

UsersManager.getDefaultDates

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

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

Callback Signature:

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

UsersManager.removeSiteAccess

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

Callback Signature:

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

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.removeSiteAccess

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

Callback Signature:

function($userLogin, $idSites)

Usages:

ScheduledReports::deleteUserReportForSites

UsersManager.updateUser.end

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

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

Callback Signature:

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

  • boolean $passwordHasBeenUpdated Flag containing information about password change.

ViewDataTable

ViewDataTable.configure

Defined in Piwik/Plugin/ViewDataTable in line 262

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

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

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

Widget

Widget.addWidgetConfigs

Defined in Piwik/Plugin/WidgetsProvider in line 63

Triggered to add custom widget configs. To filder 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 215

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 59

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