Piwik\Plugin\
Base class of plugin controllers that provide administrative functionality.
See Controller to learn more about Matomo (formerly Piwik) controllers.
This abstract class defines the following properties:
$pluginName
ash; The plugin name, eg. Inherited from Controller
$strDate
ash; The value of the date query parameter. Inherited from Controller
$date
ash; The Date object created with ($strDate)[#strDate] or null if the requested date is a range. Inherited from Controller
$idSite
ash; The value of the idSite query parameter. Inherited from Controller
$site
ash; The Site object created with $idSite. Inherited from Controller
$securityPolicy
ash; The SecurityPolicy object. Inherited from Controller
$pluginName
The plugin name, eg. 'Referrers'
.
string
value.$strDate
The value of the date query parameter.
string
value.$date
The Date object created with ($strDate)[#strDate] or null if the requested date is a range.
Date
null
$idSite
The value of the idSite query parameter.
int
value.$site
The Site object created with $idSite.
Site
value.$securityPolicy
The SecurityPolicy object.
SecurityPolicy
value.The abstract class defines the following methods:
__construct()
ash; Constructor. Inherited from Controller
getDateParameterInTimezone()
ash; Helper method that converts "today"
or "yesterday"
to the specified timezone. Inherited from Controller
setDate()
ash; Sets the date to be used by all other methods in the controller. Inherited from Controller
getDefaultAction()
ash; Returns the name of the default method that will be called when visiting: index.php?module=PluginName without the action parameter. Inherited from Controller
renderTemplate()
ash; Assigns the given variables to the template and renders it. Inherited from Controller
renderReport()
ash; Convenience method that creates and renders a ViewDataTable for a API method. Inherited from Controller
getLastUnitGraph()
ash; Returns a ViewDataTable object that will render a jqPlot evolution graph for the last30 days/weeks/etc. Inherited from Controller
getLastUnitGraphAcrossPlugins()
ash; Same as getLastUnitGraph(), but will set some properties of the ViewDataTable object based on the arguments supplied. Inherited from Controller
getUrlSparkline()
ash; Returns a URL to a sparkline image for a report served by the current plugin. Inherited from Controller
setMinDateView()
ash; Sets the first date available in the period selector's calendar. Inherited from Controller
setMaxDateView()
ash; Sets the last date available in the period selector's calendar. Inherited from Controller
setGeneralVariablesView()
ash; Assigns variables to View instances that display an entire page. Inherited from Controller
setBasicVariablesView()
ash; Assigns a set of generally useful variables to a View instance. Inherited from Controller
setHostValidationVariablesView()
ash; Checks if the current host is valid and sets variables on the given view, including: Inherited from Controller
setPeriodVariablesView()
ash; Sets general period variables on a view, including: Inherited from Controller
redirectToIndex()
ash; Helper method used to redirect the current HTTP request to another module/action. Inherited from Controller
checkTokenInUrl()
ash; Checks that the token_auth in the URL matches the currently logged-in user's token_auth. Inherited from Controller
getCalendarPrettyDate()
ash; Returns a prettified date string for use in period selector widget. Inherited from Controller
setBasicVariablesAdminView()
— Assigns view properties that would be useful to views that render admin pages.__construct()
Constructor.
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.
$date
(string
) —
'today'
, 'yesterday'
, 'YYYY-MM-DD'
$timezone
(string
) —
The timezone to use.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.
$date
(Date
) —
The new Date.void
value.getDefaultAction()
Returns the name of the default method that will be called when visiting: index.php?module=PluginName without the action parameter.
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
.
$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 }}string
value.renderReport()
Convenience method that creates and renders a ViewDataTable for a API method.
It accepts the following parameter(s):
$apiAction
$controllerAction
Returns: string
|void
—
See $fetch
.
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.
$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.ViewDataTable
value.getLastUnitGraphAcrossPlugins()
Same as getLastUnitGraph(), but will set some properties of the ViewDataTable object based on the arguments supplied.
$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.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.
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.
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).
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.
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().
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:
It accepts the following parameter(s):
$view
(View
) —It does not return anything or a mixed result.
setPeriodVariablesView()
Sets general period variables on a view, including:
array('day', 'week', 'month', 'year', 'range')
It accepts the following parameter(s):
$view
(View
) —It does not return anything or a mixed result.
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.
$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.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.
Piwik\NoAccessException
— If the token doesn't match.getCalendarPrettyDate()
Returns a prettified date string for use in period selector widget.
$period
(Period
) —
The period to return a pretty string for.string
value.setBasicVariablesAdminView()
Assigns view properties that would be useful to views that render admin pages.
Assigns the following variables:
[Tracker] record_statistics
INI
config is 0
. If not 0
, this variable will not be defined.MenuTop::getInstance()->getMenu()
.[General] enable_framed_pages
INI config option. If
true, View::setXFrameOptions() is called on the view.MenuAdmin::getInstance()->getMenu()
.It accepts the following parameter(s):
$view
(View
) —It does not return anything or a mixed result.