PHP Class Piwik\Plugin\Report

You can create a new report using the console command ./console generate:report. The generated report will guide you through the creation of a report.
Since: 2.5.0
Mostra file Open project: piwik/piwik Class Usage Examples

Protected Properties

Property Type Description
$action string The name of the action. The action is detected automatically depending on the file name. A corresponding action should exist in the API as well.
$actionToLoadSubTables string The name of the API action to load a subtable if supported. The action has to be of the same module. For instance a report "getKeywords" might support a subtable "getSearchEngines" which shows how often a keyword was searched via a specific search engine.
$categoryId string The translation key of the category the report belongs to.
$constantRowsCount boolean Set it to boolean true if your report always returns a constant count of rows, for instance always 24 rows for 1-24 hours.
$defaultSortColumn string | integer Default sort column. Either a column name or a column id.
$defaultSortOrderDesc boolean Default sort desc. If true will sort by default desc, if false will sort by default asc
$dimension Piwik\Columns\Dimension An instance of a dimension if the report has one. You can create a new dimension using the Piwik console CLI tool if needed.
$documentation string A translated documentation which explains the report.
$hasGoalMetrics boolean Set this property to true in case your report supports goal metrics. In this case, the goal metrics will be automatically added to the report metadata and the report will be displayed in the Goals UI.
$isSubtableReport boolean Set it to boolean true if this report is a subtable report and won't be used as a standalone report.
$metrics array ..)`. Defaults to the platform default metrics see {@link Metrics::getDefaultProcessedMetrics()}.
$module string The name of the module which is supposed to be equal to the name of the plugin. The module is detected automatically.
$name string The translated name of the report. The name will be used for instance in the mobile app or if another report defines this report as a related report.
$order integer The order of the report. Depending on the order the report gets a different position in the list of widgets, the menu and the mobile app.
$parameters null | array Some reports may require additional URL parameters that need to be sent when a report is requested. For instance a "goal" report might need a "goalId": array('idgoal' => 5).
$processedMetrics array Eg array('avg_time_on_site', 'nb_actions_per_visit', ...)
$recursiveLabelSeparator string Separator for building recursive labels (or paths)
$subcategoryId string The translation key of the subcategory the report belongs to.

Public Methods

Method Description
__construct ( ) The constructur initializes the module, action and the default metrics. If you want to overwrite any of those values or if you want to do any work during initializing overwrite the method {@link init()}.
alwaysUseDefaultViewDataTable ( ) : boolean Returns if the default viewDataTable type should always be used. e.g. the type won't be changeable through config or url params.
checkIsEnabled ( ) This method checks whether the report is available, see {@isEnabled()}. If not, it triggers an exception containing a message that will be displayed to the user. You can overwrite this message in case you want to customize the error message. Eg.
configureReportMetadata ( &$availableReports, $infos ) If the report is enabled the report metadata for this report will be built and added to the list of available reports. Overwrite this method and leave it empty in case you do not want your report to be added to the report metadata. In this case your report won't be visible for instance in the mobile app and scheduled reports generator. We recommend to change this behavior only if you are familiar with the Piwik core. $infos contains the current requested date, period and site.
configureView ( ViewDataTable $view ) Here you can configure how your report should be displayed and which capabilities your report has. For instance whether your report supports a "search" or not. EG $view->config->show_search = false. You can also change the default request config. For instance you can change how many rows are displayed by default: $view->requestConfig->filter_limit = 10;. See {@link ViewDataTable} for more information.
configureWidgets ( WidgetsList $widgetsList, ReportWidgetFactory $factory ) lets you add any amount of widgets for this report. If a report defines a {@link $categoryId} and a {@link $subcategoryId} a widget will be generated automatically.
fetch ( array $paramOverride = [] ) : DataTable Fetches the report represented by this instance.
fetchSubtable ( integer $idSubtable, array $paramOverride = [] ) : DataTable Fetches a subtable for the report represented by this instance.
getAction ( ) : string Get the name of the action.
getActionToLoadSubTables ( ) : string Get the action to load sub tables if one is defined.
getAllMetrics ( ) : array Returns the array of all metrics displayed by this report.
getCategoryId ( ) : string Get the translated name of the category the report belongs to.
getDefaultSortColumn ( )
getDefaultSortOrder ( )
getDefaultTypeViewDataTable ( ) : string Returns the id of the default visualization for this report. Eg 'table' or 'pie'. Defaults to the HTML table.
getDimension ( ) : Dimension
getDocumentation ( ) : string Get report documentation.
getForDimension ( Dimension $dimension ) : Report | null Finds a top level report that provides stats for a specific Dimension.
getMetrics ( ) : array Returns an array of supported metrics and their corresponding translations. Eg array('nb_visits' => 'Visits').
getMetricsForTable ( DataTable $dataTable, Report $report = null, string $baseType = 'Piwik\Plugin\Metric' ) : Metric[] Returns the Metrics that are displayed by a DataTable of a certain Report type.
getMetricsRequiredForReport ( string[] | null $allMetrics = null, string[] | null $restrictToColumns = null ) : string[] Returns the list of metrics required at minimum for a report factoring in the columns requested by the report requester.
getModule ( ) : string Get the name of the module.
getName ( ) : string Get the name of the report
getOrder ( ) : integer Returns the order of the report
getParameters ( )
getProcessedMetrics ( ) : array | mixed Returns an array of supported processed metrics and their corresponding translations. Eg array('nb_visits' => 'Visits'). By default the given {@link $processedMetrics} are used and their corresponding translations are looked up automatically. If a metric is not translated, you should add the default metric translation for this metric using the {@hook Metrics.getDefaultMetricTranslations} event. If you want to overwrite any default metric translation you should overwrite this method, call this parent method to get all default translations and overwrite any custom metric translations.
getProcessedMetricsById ( ) : Piwik\Plugin\ProcessedMetric[] Returns an array mapping the ProcessedMetrics served by this report by their string names.
getProcessedMetricsForTable ( DataTable $dataTable, Report $report = null ) : Piwik\Plugin\ProcessedMetric[] Returns the ProcessedMetrics that should be computed and formatted for a DataTable of a certain report. The ProcessedMetrics returned are those specified by the Report metadata as well as the DataTable metadata.
getRecursiveLabelSeparator ( )
getRelatedReports ( ) : Report[] Get the list of related reports if there are any. They will be displayed for instance below a report as a recommended related report.
getSubcategoryId ( ) : string Get the translated name of the subcategory the report belongs to.
getSubtableDimension ( ) : Dimension | null Returns the Dimension instance of this report's subtable report.
hasGoalMetrics ( ) : boolean
isEnabled ( ) : boolean Defines whether a report is enabled or not. For instance some reports might not be available to every user or might depend on a setting (such as Ecommerce) of a site. In such a case you can perform any checks and then return true or false. If your report is only available to users having super user access you can do the following: return Piwik::hasUserSuperUserAccess();
isSubtableReport ( ) : boolean Returns true if the report is for another report's subtable, false if otherwise.
render ( ) : string Renders a report depending on the configured ViewDataTable see {@link configureView()} and {@link getDefaultTypeViewDataTable()}. If you want to customize the render process or just render any custom view you can overwrite this method.

Protected Methods

Method Description
buildReportMetadata ( ) : array Builts the report metadata for this report. Can be useful in case you want to change the behavior of {@link configureReportMetadata()}.
getMetricsDocumentation ( ) : array Returns an array of metric documentations and their corresponding translations. Eg `array('nb_visits' => 'If a visitor comes to your website for the first time or if he visits a page more than 30 minutes after.
init ( ) Here you can do any instance initialization and overwrite any default values. You should avoid doing time consuming initialization here and if possible delay as long as possible. An instance of this report will be created in most page requests.

Private Methods

Method Description
getMetricTranslations ( $metricsToTranslate )
getSubtableApiMethod ( )

Method Details

__construct() final public method

The constructur initializes the module, action and the default metrics. If you want to overwrite any of those values or if you want to do any work during initializing overwrite the method {@link init()}.
final public __construct ( )

alwaysUseDefaultViewDataTable() public method

Defaults to false

buildReportMetadata() protected method

Builts the report metadata for this report. Can be useful in case you want to change the behavior of {@link configureReportMetadata()}.
protected buildReportMetadata ( ) : array
return array

checkIsEnabled() public method

if (!$this->isEnabled()) { throw new Exception('Setting XYZ is not enabled or the user has not enough permission'); }
public checkIsEnabled ( )

configureReportMetadata() public method

If the report is enabled the report metadata for this report will be built and added to the list of available reports. Overwrite this method and leave it empty in case you do not want your report to be added to the report metadata. In this case your report won't be visible for instance in the mobile app and scheduled reports generator. We recommend to change this behavior only if you are familiar with the Piwik core. $infos contains the current requested date, period and site.
public configureReportMetadata ( &$availableReports, $infos )
$availableReports
$infos

configureView() public method

Here you can configure how your report should be displayed and which capabilities your report has. For instance whether your report supports a "search" or not. EG $view->config->show_search = false. You can also change the default request config. For instance you can change how many rows are displayed by default: $view->requestConfig->filter_limit = 10;. See {@link ViewDataTable} for more information.
public configureView ( ViewDataTable $view )
$view ViewDataTable

configureWidgets() public method

Example to add a widget manually by overwriting this method in your report: $widgetsList->addWidgetConfig($factory->createWidget()); If you want to have the name and the order of the widget differently to the name and order of the report you can do the following: $widgetsList->addWidgetConfig($factory->createWidget()->setName('Custom')->setOrder(5)); If you want to add a widget to any container defined by your plugin or by another plugin you can do this: $widgetsList->addToContainerWidget($containerId = 'Products', $factory->createWidget());
public configureWidgets ( WidgetsList $widgetsList, ReportWidgetFactory $factory )
$widgetsList Piwik\Widget\WidgetsList
$factory Piwik\Report\ReportWidgetFactory

fetch() public method

Fetches the report represented by this instance.
public fetch ( array $paramOverride = [] ) : DataTable
$paramOverride array Query parameter overrides.
return Piwik\DataTable

fetchSubtable() public method

Fetches a subtable for the report represented by this instance.
public fetchSubtable ( integer $idSubtable, array $paramOverride = [] ) : DataTable
$idSubtable integer The subtable ID.
$paramOverride array Query parameter overrides.
return Piwik\DataTable

getAction() public method

Get the name of the action.
public getAction ( ) : string
return string

getActionToLoadSubTables() public method

Get the action to load sub tables if one is defined.
public getActionToLoadSubTables ( ) : string
return string

getAllMetrics() public method

Returns the array of all metrics displayed by this report.
public getAllMetrics ( ) : array
return array

getCategoryId() public method

Get the translated name of the category the report belongs to.
public getCategoryId ( ) : string
return string

getDefaultSortColumn() public method

getDefaultSortOrder() public method

public getDefaultSortOrder ( )

getDefaultTypeViewDataTable() public method

Returns the id of the default visualization for this report. Eg 'table' or 'pie'. Defaults to the HTML table.

getDimension() public method

public getDimension ( ) : Dimension
return Piwik\Columns\Dimension

getDocumentation() public method

Get report documentation.
public getDocumentation ( ) : string
return string

getForDimension() public static method

Finds a top level report that provides stats for a specific Dimension.
public static getForDimension ( Dimension $dimension ) : Report | null
$dimension Piwik\Columns\Dimension The dimension whose report we're looking for.
return Report | null The

getMetrics() public method

By default the given {@link $metrics} are used and their corresponding translations are looked up automatically. If a metric is not translated, you should add the default metric translation for this metric using the {@hook Metrics.getDefaultMetricTranslations} event. If you want to overwrite any default metric translation you should overwrite this method, call this parent method to get all default translations and overwrite any custom metric translations.
public getMetrics ( ) : array
return array

getMetricsDocumentation() protected method

..')`. By default the given {@link $metrics} are used and their corresponding translations are looked up automatically. If there is a metric documentation not found, you should add the default metric documentation translation for this metric using the {@hook Metrics.getDefaultMetricDocumentationTranslations} event. If you want to overwrite any default metric translation you should overwrite this method, call this parent method to get all default translations and overwrite any custom metric translations.
protected getMetricsDocumentation ( ) : array
return array

getMetricsForTable() public static method

Includes ProcessedMetrics and Metrics.
public static getMetricsForTable ( DataTable $dataTable, Report $report = null, string $baseType = 'Piwik\Plugin\Metric' ) : Metric[]
$dataTable Piwik\DataTable
$report Report
$baseType string The base type each metric class needs to be of.
return Metric[]

getMetricsRequiredForReport() public method

This will return all the metrics requested (or all the metrics in the report if nothing is requested) **plus** the metrics required to calculate the requested processed metrics. This method should be used in **Plugin.get** API methods.
public getMetricsRequiredForReport ( string[] | null $allMetrics = null, string[] | null $restrictToColumns = null ) : string[]
$allMetrics string[] | null The list of all available unprocessed metrics. Defaults to this report's metrics.
$restrictToColumns string[] | null The requested columns.
return string[]

getModule() public method

Get the name of the module.
public getModule ( ) : string
return string

getName() public method

Get the name of the report
public getName ( ) : string
return string

getOrder() public method

Returns the order of the report
public getOrder ( ) : integer
return integer

getParameters() public method

public getParameters ( )

getProcessedMetrics() public method

Returns an array of supported processed metrics and their corresponding translations. Eg array('nb_visits' => 'Visits'). By default the given {@link $processedMetrics} are used and their corresponding translations are looked up automatically. If a metric is not translated, you should add the default metric translation for this metric using the {@hook Metrics.getDefaultMetricTranslations} event. If you want to overwrite any default metric translation you should overwrite this method, call this parent method to get all default translations and overwrite any custom metric translations.
public getProcessedMetrics ( ) : array | mixed
return array | mixed

getProcessedMetricsById() public method

Returns an array mapping the ProcessedMetrics served by this report by their string names.
public getProcessedMetricsById ( ) : Piwik\Plugin\ProcessedMetric[]
return Piwik\Plugin\ProcessedMetric[]

getProcessedMetricsForTable() public static method

Returns the ProcessedMetrics that should be computed and formatted for a DataTable of a certain report. The ProcessedMetrics returned are those specified by the Report metadata as well as the DataTable metadata.
public static getProcessedMetricsForTable ( DataTable $dataTable, Report $report = null ) : Piwik\Plugin\ProcessedMetric[]
$dataTable Piwik\DataTable
$report Report
return Piwik\Plugin\ProcessedMetric[]

getRecursiveLabelSeparator() public method

getRelatedReports() public method

Get the list of related reports if there are any. They will be displayed for instance below a report as a recommended related report.
public getRelatedReports ( ) : Report[]
return Report[]

getSubcategoryId() public method

Get the translated name of the subcategory the report belongs to.
public getSubcategoryId ( ) : string
return string

getSubtableDimension() public method

Returns the Dimension instance of this report's subtable report.
public getSubtableDimension ( ) : Dimension | null
return Piwik\Columns\Dimension | null The subtable report's dimension or null if there is subtable report or no dimension for the subtable report.

hasGoalMetrics() public method

public hasGoalMetrics ( ) : boolean
return boolean

init() protected method

Here you can do any instance initialization and overwrite any default values. You should avoid doing time consuming initialization here and if possible delay as long as possible. An instance of this report will be created in most page requests.
protected init ( )

isEnabled() public method

Defines whether a report is enabled or not. For instance some reports might not be available to every user or might depend on a setting (such as Ecommerce) of a site. In such a case you can perform any checks and then return true or false. If your report is only available to users having super user access you can do the following: return Piwik::hasUserSuperUserAccess();
public isEnabled ( ) : boolean
return boolean

isSubtableReport() public method

Returns true if the report is for another report's subtable, false if otherwise.
public isSubtableReport ( ) : boolean
return boolean

render() public method

Renders a report depending on the configured ViewDataTable see {@link configureView()} and {@link getDefaultTypeViewDataTable()}. If you want to customize the render process or just render any custom view you can overwrite this method.
public render ( ) : string
return string

Property Details

$action protected_oe property

The name of the action. The action is detected automatically depending on the file name. A corresponding action should exist in the API as well.
protected string $action
return string

$actionToLoadSubTables protected_oe property

The name of the API action to load a subtable if supported. The action has to be of the same module. For instance a report "getKeywords" might support a subtable "getSearchEngines" which shows how often a keyword was searched via a specific search engine.
protected string $actionToLoadSubTables
return string

$categoryId protected_oe property

The translation key of the category the report belongs to.
protected string $categoryId
return string

$constantRowsCount protected_oe property

Set it to boolean true if your report always returns a constant count of rows, for instance always 24 rows for 1-24 hours.
protected bool $constantRowsCount
return boolean

$defaultSortColumn protected_oe property

Default sort column. Either a column name or a column id.
protected string|int $defaultSortColumn
return string | integer

$defaultSortOrderDesc protected_oe property

Default sort desc. If true will sort by default desc, if false will sort by default asc
protected bool $defaultSortOrderDesc
return boolean

$dimension protected_oe property

An instance of a dimension if the report has one. You can create a new dimension using the Piwik console CLI tool if needed.
protected Dimension,Piwik\Columns $dimension
return Piwik\Columns\Dimension

$documentation protected_oe property

A translated documentation which explains the report.
protected string $documentation
return string

$hasGoalMetrics protected_oe property

Set this property to true in case your report supports goal metrics. In this case, the goal metrics will be automatically added to the report metadata and the report will be displayed in the Goals UI.
protected bool $hasGoalMetrics
return boolean

$isSubtableReport protected_oe property

Set it to boolean true if this report is a subtable report and won't be used as a standalone report.
protected bool $isSubtableReport
return boolean

$metrics protected_oe property

..)`. Defaults to the platform default metrics see {@link Metrics::getDefaultProcessedMetrics()}.
protected array $metrics
return array

$module protected_oe property

The name of the module which is supposed to be equal to the name of the plugin. The module is detected automatically.
protected string $module
return string

$name protected_oe property

The translated name of the report. The name will be used for instance in the mobile app or if another report defines this report as a related report.
protected string $name
return string

$order protected_oe property

The order of the report. Depending on the order the report gets a different position in the list of widgets, the menu and the mobile app.
protected int $order
return integer

$parameters protected_oe property

Some reports may require additional URL parameters that need to be sent when a report is requested. For instance a "goal" report might need a "goalId": array('idgoal' => 5).
protected null|array $parameters
return null | array

$processedMetrics protected_oe property

Eg array('avg_time_on_site', 'nb_actions_per_visit', ...)
protected array $processedMetrics
return array

$recursiveLabelSeparator protected_oe property

Separator for building recursive labels (or paths)
protected string $recursiveLabelSeparator
return string

$subcategoryId protected_oe property

The translation key of the subcategory the report belongs to.
protected string $subcategoryId
return string