API Reference

Report

Piwik\Plugin\

Report

Since Matomo 2.5.0

Defines a new 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.

Properties

This class defines the following properties:

  • $name — The translated name of the report.
  • $categoryId — The translation key of the category the report belongs to.
  • $subcategoryId — The translation key of the subcategory the report belongs to.
  • $metrics — An array of supported metrics.
  • $processedMetrics — The processed metrics this report supports, eg avg_time_on_site or nb_actions_per_visit.
  • $hasGoalMetrics — Set this property to true in case your report supports goal metrics.
  • $supportsFlatten — Set this property to false in case your report can't/shouldn't be flattened.
  • $constantRowsCount — Set it to boolean true if your report always returns a constant count of rows, for instance always 24 rows for 1-24 hours.
  • $isSubtableReport — Set it to boolean true if this report is a subtable report and won't be used as a standalone report.
  • $parameters — Some reports may require additional URL parameters that need to be sent when a report is requested.
  • $actionToLoadSubTables — The name of the API action to load a subtable if supported.
  • $order — The order of the report.
  • $recursiveLabelSeparator — Separator for building recursive labels (or paths)

$name

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.

Signature

  • It is a string value.

$categoryId

The translation key of the category the report belongs to.

Signature

  • It can be one of the following types:
    • string
    • null

$subcategoryId

The translation key of the subcategory the report belongs to.

Signature

  • It can be one of the following types:
    • string
    • null

$metrics

An array of supported metrics. Eg `array('nb_visits', 'nb_actions', .

..)`. Defaults to the platform default metrics see Metrics::getDefaultProcessedMetrics().

Signature

  • It is a array value.

$processedMetrics

The processed metrics this report supports, eg avg_time_on_site or nb_actions_per_visit. Defaults to the platform default processed metrics, see Metrics::getDefaultProcessedMetrics(). Set it to boolean false if your report does not support any processed metrics at all. Otherwise an array of metric names.

Eg array('avg_time_on_site', 'nb_actions_per_visit', ...)

Signature

  • It is a array value.

$hasGoalMetrics

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.

Signature

  • It is a bool value.

$supportsFlatten

Set this property to false in case your report can't/shouldn't be flattened.

In this case, flattener won't be applied even if parameter is provided in a request

Signature

  • It is a bool value.

$constantRowsCount

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

Signature

  • It is a bool value.

$isSubtableReport

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

Signature

  • It is a bool value.

$parameters

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).

Signature

  • It can be one of the following types:
    • null
    • array

$actionToLoadSubTables

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.

Signature

  • It is a string value.

$order

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.

Signature

  • It is a int value.

$recursiveLabelSeparator

Separator for building recursive labels (or paths)

Signature

  • It is a string value.

Methods

The class defines the following methods:

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.

Signature

  • It does not return anything or a mixed result.

isEnabled()

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();

Signature

  • It returns a bool value.

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.

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

Signature

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

getDefaultTypeViewDataTable()

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

Signature

  • It returns a string value.

alwaysUseDefaultViewDataTable()

Returns if the default viewDataTable type should always be used. e.g. the type won't be changeable through config or url params.

Defaults to false

Signature

  • It returns a bool value.

configureView()

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 ViewDataTable for more information.

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

render()

Renders a report depending on the configured ViewDataTable see configureView() and getDefaultTypeViewDataTable(). If you want to customize the render process or just render any custom view you can overwrite this method.

Signature

  • It returns a string value.
  • It throws one of the following exceptions:
    • Exception — In case the given API action does not exist yet.

getId()

Processing a uniqueId for each report, can be used by UIs as a key to match a given report

Signature

  • It returns a string value.

configureWidgets()

lets you add any amount of widgets for this report. If a report defines a $categoryId and a $subcategoryId a widget will be generated automatically.

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());

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

getMetrics()

Returns an array of supported metrics and their corresponding translations. Eg array('nb_visits' => 'Visits').

By default the given $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 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.

Signature

  • It returns a array value.

getMetricsRequiredForReport()

Returns the list of metrics required at minimum for a report factoring in the columns requested by the report requester.

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.

Signature

  • It accepts the following parameter(s):
    • $allMetrics (string[]|null) — The list of all available unprocessed metrics. Defaults to this report's metrics.
    • $restrictToColumns (string[]|null) — The requested columns.
  • It returns a string[] value.

getProcessedMetrics()

Returns an array of supported processed metrics and their corresponding translations. Eg array('nb_visits' => 'Visits'). By default the given $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 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.

Signature

  • Returns: array|mixed —

getMetricSemanticTypes()

Returns the semantic types for metrics this report displays.

If the semantic type is not defined by the derived Report class, it defaults to the value returned by Metrics::getDefaultMetricSemanticTypes() or Metric::getSemanticType(). If the semantic type cannot be found this way, this method tries to deduce it from the metric name, though this process will not identify the semantic type for most metrics.

Signature

  • Returns: array — maps metric name => semantic type

getAllMetrics()

Returns the array of all metrics displayed by this report.

Signature

  • It returns a array value.

getMetricNamesToProcessReportTotals()

Use this method to register metrics to process report totals.

When a metric is registered, it will process the report total values and as a result show percentage values in the HTML Table reporting visualization.

Signature

  • Returns: string[] — metricId => metricColumn, if the report has only column names and no IDs, it should return metricColumn => metricColumn, eg array('13' => 'nb_pageviews') or array('mymetric' => 'mymetric')

getMetricsDocumentation()

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 they visit a page more than 30 minutes after.

..')`. By default the given $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 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.

Signature

  • It returns a array value.

configureReportMetadata()

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 Matomo (formerly Piwik) core. $infos contains the current requested date, period and site.

Signature

  • It accepts the following parameter(s):

    • $availableReports

    • $infos

  • It does not return anything or a mixed result.

getDocumentation()

Get report documentation.

Signature

  • It returns a string value.

getSecondarySortColumnCallback()

Allows to define a callback that will be used to determine the secondary column to sort by

public function getSecondarySortColumnCallback()
{
    return function ($primaryColumn) {
        switch ($primaryColumn) {
            case Metrics::NB_CLICKS:
                return Metrics::NB_IMPRESSIONS;
            case 'label':
            default:
                return Metrics::NB_CLICKS;
        }
    };
}

Signature

  • Returns: null|callable —

getRelatedReports()

Get the list of related reports if there are any. They will be displayed for instance below a report as a recommended related report.

Signature

getParameters()

Signature

  • It does not return anything or a mixed result.

getSubtableDimension()

Returns the Dimension instance of this report's subtable report.

Signature

  • Returns: Dimension|null — The subtable report's dimension or null if there is subtable report or no dimension for the subtable report.

getThirdLeveltableDimension()

Returns the Dimension instance of the subtable report of this report's subtable report.

Signature

  • Returns: Dimension|null — The subtable report's dimension or null if there is no subtable report or no dimension for the subtable report.

isSubtableReport()

Returns true if the report is for another report's subtable, false if otherwise.

Signature

  • It returns a bool value.

fetch()

Fetches the report represented by this instance.

Signature

  • It accepts the following parameter(s):
    • $paramOverride (array) — Query parameter overrides.
  • It returns a DataTable value.

fetchSubtable()

Fetches a subtable for the report represented by this instance.

Signature

  • It accepts the following parameter(s):
    • $idSubtable (int) — The subtable ID.
    • $paramOverride (array) — Query parameter overrides.
  • It returns a DataTable value.

getForDimension()

Finds a top level report that provides stats for a specific Dimension.

Signature

  • It accepts the following parameter(s):

    • $dimension (Dimension) — The dimension whose report we're looking for.

  • Returns: Report|null — The

getProcessedMetricsById()

Returns an array mapping the ProcessedMetrics served by this report by their string names.

Signature

getMetricsForTable()

Returns the Metrics that are displayed by a DataTable of a certain Report type.

Includes ProcessedMetrics and Metrics.

Signature

  • It accepts the following parameter(s):

    • $dataTable (DataTable) —

    • $report (Report) —

    • $baseType (string) — The base type each metric class needs to be of.

  • It returns a Metric[] value.

getProcessedMetricsForTable()

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.

Signature

getRowIdentifier()

Returns the name of the column/metadata that uniquely identifies rows in this report. See self::$rowIdentifier for more information.

Signature

  • It returns a string value.