Docs › Framework Reference – Hooks

  1. List of hooks
  2. Register an action for a given hook
  3. Add a new hook

List of hooks

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

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

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

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

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

Defines which website to load by default when visiting Piwik

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

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)

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

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

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

Dispatcher for core and plugin updates.
Argument: None

Check for Piwik software updates.
Argument: None

Load database schema.
Argument: $schema

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

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

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

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

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

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

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

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

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

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

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

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

Instantiate a new Action object.
Argument: $action

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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.

You may also be interested in...

Documentation feedback

Have you found an error in this page, or do you think some information is missing or not clear?
Your comments, suggestions, and ideas for improvements to this documentation are very important to us. We appreciate you taking the time to send us this information.



Keywords used to find this page: Keyword not defined, piwik register new search engine


This list top keywords was displayed using a Piwik Widget "Top Keywords Widget". You can access it in your Piwik: click on Widgets, and look under the Referrers category.

Entries (RSS)