API Reference

Controller

Piwik\Plugin\

Controller

Base class of all plugin Controllers.

Plugins that wish to add display HTML should create a Controller that either extends from this class or from ControllerAdmin. Every public method in the controller will be exposed as a controller method and can be invoked via an HTTP request.

Learn more about Matomo (formerly Piwik)'s MVC system here.

Examples

Defining a controller

class Controller extends \Piwik\Plugin\Controller
{
    public function index()
    {
        $view = new View("@MyPlugin/index.twig");
        // ... setup view ...
        return $view->render();
    }
}

Linking to a controller action

<a href="?module=MyPlugin&action=index&idSite=1&period=day&date=2013-10-10">Link</a>

Properties

This abstract class defines the following properties:

  • $pluginName — The plugin name, eg.
  • $strDate — The value of the date query parameter.
  • $date — The Date object created with ($strDate)[#strDate] or null if the requested date is a range.
  • $idSite — The value of the idSite query parameter.
  • $site ash; The Site object created with $idSite.
  • $securityPolicy — The SecurityPolicy object.

$pluginName

The plugin name, eg. 'Referrers'.

Signature

  • It is a string value.

$strDate

The value of the date query parameter.

Signature

  • It is a string value.

$date

The Date object created with ($strDate)[#strDate] or null if the requested date is a range.

Signature

  • It can be one of the following types:

$idSite

The value of the idSite query parameter.

Signature

  • It is a int value.

$site

The Site object created with $idSite.

Signature

  • It is a Site value.

$securityPolicy

The SecurityPolicy object.

Signature

Methods

The abstract class defines the following methods:

__construct()

Constructor.

Signature

getDateParameterInTimezone()

Helper method that converts "today" or "yesterday" to the specified timezone.

If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone.

Signature

  • It accepts the following parameter(s):
    • $date (string) — 'today', 'yesterday', 'YYYY-MM-DD'
    • $timezone (string) — The timezone to use.
  • It returns a Date value.

setDate()

Sets the date to be used by all other methods in the controller.

If the date has to be modified, this method should be called just after construction.

Signature

  • It accepts the following parameter(s):
    • $date (Date) — The new Date.
  • It returns a void value.

getDefaultAction()

Returns the name of the default method that will be called when visiting: index.php?module=PluginName without the action parameter.

Signature

  • It returns a string value.

renderTemplate()

Since Matomo 2.5.0

Assigns the given variables to the template and renders it.

Example:

public function myControllerAction () {
   return $this->renderTemplate('index', array(
       'answerToLife' => '42'
   ));
}

This will render the 'index.twig' file within the plugin templates folder and assign the view variable answerToLife to 42.

Signature

  • It accepts the following parameter(s):
    • $template (string) — The name of the template file. If only a name is given it will automatically use the template within the plugin folder. For instance 'myTemplate' will result in '@$pluginName/myTemplate.twig'. Alternatively you can include the full path: '@anyOtherFolder/otherTemplate'. The trailing '.twig' is not needed.
    • $variables (array) — For instance array('myViewVar' => 'myValue'). In template you can use {{ myViewVar }}
  • It returns a string value.

renderReport()

Convenience method that creates and renders a ViewDataTable for a API method.

Signature

  • It accepts the following parameter(s):

    • $apiAction

    • $controllerAction

  • Returns: string|void — See $fetch.

  • It throws one of the following exceptions:
    • Exception — if $pluginName is not an existing plugin or if $apiAction is not an existing method of the plugin's API.

getLastUnitGraph()

Returns a ViewDataTable object that will render a jqPlot evolution graph for the last30 days/weeks/etc. of the current period, relative to the current date.

Signature

  • It accepts the following parameter(s):
    • $currentModuleName (string) — The name of the current plugin.
    • $currentControllerAction (string) — The name of the action that renders the desired report.
    • $apiMethod (string) — The API method that the ViewDataTable will use to get graph data.
  • It returns a ViewDataTable value.

getLastUnitGraphAcrossPlugins()

Same as getLastUnitGraph(), but will set some properties of the ViewDataTable object based on the arguments supplied.

Signature

  • It accepts the following parameter(s):
    • $currentModuleName (string) — The name of the current plugin.
    • $currentControllerAction (string) — The name of the action that renders the desired report.
    • $columnsToDisplay (array) — The value to use for the ViewDataTable's columns_to_display config property.
    • $selectableColumns (array) — The value to use for the ViewDataTable's selectable_columns config property.
    • $reportDocumentation (bool|string) — The value to use for the ViewDataTable's documentation config property.
    • $apiMethod (string) — The API method that the ViewDataTable will use to get graph data.
  • It returns a ViewDataTable value.

getUrlSparkline()

Returns a URL to a sparkline image for a report served by the current plugin.

The result of this URL should be used with the sparkline() twig function.

The current site ID and period will be used.

Signature

  • It accepts the following parameter(s):

    • $action (string) — Method name of the controller that serves the report.
    • $customParameters (array) — The array of query parameter name/value pairs that should be set in result URL.

  • Returns: string — The generated URL.

setMinDateView()

Sets the first date available in the period selector's calendar.

Signature

  • It accepts the following parameter(s):
    • $minDate (Date) — The min date.
    • $view (View) — The view that contains the period selector.
  • It does not return anything or a mixed result.

setMaxDateView()

Sets the last date available in the period selector's calendar. Usually this is just the "today" date for a site (which varies based on the timezone of a site).

Signature

  • It accepts the following parameter(s):
    • $maxDate (Date) — The max date.
    • $view (View) — The view that contains the period selector.
  • It does not return anything or a mixed result.

setGeneralVariablesView()

Assigns variables to View instances that display an entire page.

The following variables assigned:

date - The value of the date query parameter. idSite - The value of the idSite query parameter. rawDate - The value of the date query parameter. prettyDate - A pretty string description of the current period. siteName - The current site's name. siteMainUrl - The URL of the current site. startDate - The start date of the current period. A Date instance. endDate - The end date of the current period. A Date instance. language - The current language's language code. config_action_url_category_delimiter - The value of the [General] action_url_category_delimiter INI config option. topMenu - The result of MenuTop::getInstance()->getMenu().

As well as the variables set by setPeriodVariablesView().

Will exit on error.

Signature

  • It accepts the following parameter(s):

    • $view

  • It returns a void value.

setBasicVariablesView()

Assigns a set of generally useful variables to a View instance.

The following variables assigned:

isSuperUser - True if the current user is the Super User, false if otherwise. hasSomeAdminAccess - True if the current user has admin access to at least one site, false if otherwise. isCustomLogo - The value of the branding_use_custom_logo option. logoHeader - The header logo URL to use. logoLarge - The large logo URL to use. logoSVG - The SVG logo URL to use. hasSVGLogo - True if there is a SVG logo, false if otherwise. enableFrames - The value of the [General] enable_framed_pages INI config option. If true, View::setXFrameOptions() is called on the view.

Also calls setHostValidationVariablesView().

Signature

  • It accepts the following parameter(s):

    • $view

  • It does not return anything or a mixed result.

setHostValidationVariablesView()

Checks if the current host is valid and sets variables on the given view, including:

  • isValidHost - true if host is valid, false if otherwise
  • invalidHostMessage - message to display if host is invalid (only set if host is invalid)
  • invalidHost - the invalid hostname (only set if host is invalid)
  • mailLinkStart - the open tag of a link to email the Super User of this problem (only set if host is invalid)

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

setPeriodVariablesView()

Sets general period variables on a view, including:

  • displayUniqueVisitors - Whether unique visitors should be displayed for the current period.
  • period - The value of the period query parameter.
  • otherPeriods - array('day', 'week', 'month', 'year', 'range')
  • periodsNames - List of available periods mapped to their singular and plural translations.

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

  • It throws one of the following exceptions:
    • Exception — if the current period is invalid.

redirectToIndex()

Helper method used to redirect the current HTTP request to another module/action.

This function will exit immediately after executing.

Signature

  • It accepts the following parameter(s):
    • $moduleToRedirect (string) — The plugin to redirect to, eg. "MultiSites".
    • $actionToRedirect (string) — Action, eg. "index".
    • $websiteId (int|null) — The new idSite query parameter, eg, 1.
    • $defaultPeriod (string|null) — The new period query parameter, eg, 'day'.
    • $defaultDate (string|null) — The new date query parameter, eg, 'today'.
    • $parameters (array) — Other query parameters to append to the URL.
  • It does not return anything or a mixed result.

checkTokenInUrl()

Checks that the token_auth in the URL matches the currently logged-in user's token_auth.

This is a protection against CSRF and should be used in all controller methods that modify Matomo or any user settings.

If called from JavaScript by using the ajaxHelper you have to call ajaxHelper.withTokenInUrl(); before ajaxHandler.send(); to send the token along with the request.

The token_auth should never appear in the browser's address bar.

Signature

  • It does not return anything or a mixed result.
  • It throws one of the following exceptions:

getCalendarPrettyDate()

Returns a prettified date string for use in period selector widget.

Signature

  • It accepts the following parameter(s):
    • $period (Period) — The period to return a pretty string for.
  • It returns a string value.