Framework Reference – Hooks

List of hooks

• API.Request.authenticate (view in source)

This hook is called when a token appears in the API request. (See plugins/Login/Login.php for usage.)
Argument: string $token_auth

• ArchiveProcessing_Day.compute (view in source)

This hook is called when computing the archiving for a day. Useful for plugins that want to archive data.
Argument: object ArchiveProcessing_Day

• ArchiveProcessing_Period.compute (view in source)

This hook is called when computing the archiving for a period. Useful for plugins that want to archive data.
Argument: object ArchiveProcessing_Period

• Common.fetchWebsiteAttributes (view in source)

This hook is called to fetch website attributes from the plugins (e.g., Goals and SitesManager)
Arguments: array $attributes, int $idSite

• Common.getCountry (view in source)

This hook is called to get the visitor’s country from his/her IP address
Arguments: string $ip

• Controller.getDefaultWebsiteId (view in source)

Defines which website to load by default when visiting Piwik

• Controller.renderView (view in source)

Call object to render view of data table.
Argument: array containing Piwik_ViewDataTable $view, controllerName, controllerAction, apiMethodToRequestDataTable, controllerActionCalledWhenRequestSubTable

• FrontController.dispatch (view in source)

This hook is called before every call to a Controller method. It can be used to modify the plugin and action to call, to log additional data, modify the parameters, etc.

Argument: array ( $controllerObject, $actionString, $parametersArray)

• FrontController.NoAccessException (view in source)

Called when a user visits Piwik interface or calls the API without having the requested access rights.
Argument: The exception Piwik_Access_NoAccessException

• FrontController.NoConfigurationFile (view in source)

Called when the configuration file couldn’t be found, usually when Piwik was not installed yet.
Argument: The exception thrown

• FrontController.initAuthenticationObject (view in source)

This hook is used by the Login plugin to initialize the Piwik_Auth authentication object. This object is stored in the Zend_Registry object. More info in /plugins/Login/Login.php.
Argument: None

• FrontController.dispatchCoreAndPluginUpdatesScreen (view in source)

Dispatcher for core and plugin updates.
Argument: None

• FrontController.checkForUpdates (view in source)

Check for Piwik software updates.
Argument: None

• Schema.loadSchema (view in source)

Load database schema.
Argument: $schema

• Reporting.getDatabaseConfig (view in source)

This hook is called before Piwik connects to the database.
Argument: $dbInfo

• Reporting.createDatabase (view in source)

This hook is called when the Piwik UI (or API) connects to the database.
Argument: $db

• Tracker.getDatabaseConfig (view in source)

This hook is called before Piwik connects to the database.
Argument: $dbInfo

• Tracker.createDatabase (view in source)

This hook is called when the Tracker connects to the database.
Argument: $db

• Tracker.getNewVisitObject (view in source)

Instantiate a new Visit object, other than Piwik_Tracker_Visit.
Argument: $visit

• Tracker.setRequest.idSite (view in source)

This hook allows a plugin to set/change the idsite in the tracking request.
Argument: int $idsite

• Tracker.Visit.isExcluded (view in source)

At every page view, this hook will be called. Useful for plugins that want to exclude specific visits (ie. IP excluding, Cookie excluding)
Argument: boolean $excluded if set to false, no statistics will be logged for this page

• Tracker.newVisitorInformation (view in source)

When a new visitor is being logged by Piwik, this hook is called. Useful for plugins that want to register new information about the visitor, or filter the existing information.
Argument: array $informationToSave containing pairs of name,value to be recorded in the log_visit table

• Tracker.knownVisitorUpdate (view in source)

Before a known visitor is logged by Piwik, this hook is called.
Argument: array $valuesToUpdate

• Tracker.knownVisitorInformation (view in source)

After a known visitor is logged by Piwik, this hook is called. Useful for plugins that want to register information about a returning visitor, or filter the existing information.
Argument: array $informationToSave containing pairs of name,value to be recorded in the log_visit table

• Tracker.saveVisitorInformation (view in source)

This hook is called before saving visitor information.
Argument: $visitor_information

• Tracker.saveVisitorInformation.end (view in source)

This hook is called after saving (and updating) visitor information.
Argument: $visitor_information

• Tracker.newAction (view in source)

Instantiate a new Action object.
Argument: $action

• Tracker.Action.record (view in source)

Called after an Action has been logged.
Argument: $action_information

• Tracker.detectRefererSearchEngine (view in source)

Called after basic search engine detection has been attempted. Plugin can modify or provide new results.
Argument: array $searchEngineInformation Argument: string $rawRefererUrl

• Translate.getLanguageToLoad (view in source)

This hook is called with the name of the language to load.
Argument: string $language

• View.getViewType (view in source)

This hook is called to get the view type (e.g., Piwik_View::STANDARD, Piwik_View::MOBILE, or Piwik_View::CLI).
Argument: int $viewType

• SitesManager.addSite (view in source)

This hook is called when a site is added.
Argument: string $idSite

• SitesManager.updateSite (view in source)

This hook is called when a site is updated.
Argument: string $idSite

• SitesManager.deleteSite (view in source)

This hook is called when a site is deleted.
Argument: string $idSite

• UsersManager.addUser (view in source)

This hook is called when a user is added.
Argument: string $userLogin

• UsersManager.updateUser (view in source)

This hook is called when a user is updated.
Argument: string $userLogin

• UsersManager.deleteUser (view in source)

This hook is called when a user is deleted.
Argument: string $userLogin

• InstallationController.construct (view in source)

Called at the end of the InstallationController constructor. Useful for plugins that want to modify the installation process (adding/removing steps, removing steps, etc.).
Argument: The object InstallationController

• Installation.startInstallation (view in source)

Useful for plugins that want to change the Installation controller using setControllerToLoad().
Argument: The object InstallationController

• Referers.archiveDay (view in source)

Called by Referers plugin during its response to ArchiveProcessing_Day.compute hook.
Argument: None

• Goals.getReportsWithGoalMetrics (view in source)

Called to define available goal segments.
Argument: array $segments

• Menu.add (view in source)

Hook for plugins to add items to menu.
Argument: None

• AdminMenu.add (view in source)

Hook for plugins to add items to administrator menu.
Argument: None

• WidgetsList.add (view in source)

Hook for plugins to add items to widget list.
Argument: None

• Provider.getCleanHostname (view in source)

Hook for plugins to provide a clean host name (without the top level domain).
Argument: $hostname

• template_js_import (Deprecated, use AssetManager.getJsFiles hook)

Called within Smarty template to add (JavaScript) script elements to page (via echo).
Argument: $str (unused)

• template_css_import (Deprecated, use AssetManager.getCssFiles hook)

Called within Smarty template to add CSS link elements to page (via echo).
Argument: $str (unused)

• AssetManager.getJsFiles (view in source)

This hook is sent by the AssetManager to list the required Javascript files. Plugins can hook to this event if they require Javascript files.
Argument: array $jsFiles

• AssetManager.getCssFiles (view in source)

This hook is sent by the AssetManager to list the required CSS files. Plugins can hook to this event if they require CSS files.
Argument: array $cssFiles

Register an action for a given hook

If you want to listen to a specific event, and trigger your own function when this event is posted, you have to define a method getListHooksRegistered() in your plugin class, that will return an array containing pair of (hook name, method to call).

For example if you want to execute your function AddCityInformation() when a new visitor is recorded by Piwik (hook ‘Tracker.newVisitorInformation’), in your class Piwik_MyPlugin you would define a method:

function getListHooksRegistered()
{
    return array( 'Tracker.newVisitorInformation' => 'AddCityInformation' );
}

The hook Tracker.newVisitorInformation has an argument: an array containing the visitor’s information. You can add new elements to this array. Example:

function AddCityInformation( $notification )
{
     // we get the argument by reference associated with the hook
     $visitorInfo =& $notification->getNotificationObject();
     // we modify the variable, adding the new city field
     $visitorInfo['city'] = 'Paris, France';
}

You can have a look at the provider plugin to see an example of a plugin registering actions for multiple hooks.

Piwik also provides a means of dynamic hook registration using Piwik_AddAction( $eventName, $callback ).

Add a new hook

Plugins can themselves post new events, the same way Piwik posts events. A common example is custom page headers and footers (on a per plugin basis).

    Piwik_PostEvent( $eventName,  [ $object , [ $info ]])

or in Smarty templates:

    {postEvent name="$eventName"}

By convention, the event name should be prefixed by the Plugin name.