Click here if you want to read this article for the latest Piwik version

Piwik\Plugin\

Report

Since Piwik 2.5.0

Defines a new report.

This class contains all information a report defines except the corresponding API method which needs to be defined in the 'API.php'. You can define the name of the report, a documentation, the supported metrics, how the report should be displayed, which features the report has (eg search) and much more.

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.
  • $category — The translation key of the category the report belongs to.
  • $widgetTitle — The translation key of the widget title.
  • $widgetParams ash; Optional widget params that will be appended to the widget URL if a $widgetTitle is set.
  • $menuTitle — The translation key of the menu title.
  • $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.
  • $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)
  • $orderOfReports

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

$category

The translation key of the category the report belongs to.

Signature

  • It is a string value.

$widgetTitle

The translation key of the widget title.

If a widget title is set, the platform will automatically configure/add a widget for this report. Alternatively, this behavior can be overwritten in configureWidget().

Signature

  • It is a string value.

$widgetParams

Optional widget params that will be appended to the widget URL if a $widgetTitle is set.

Signature

  • It is a array value.

The translation key of the menu title.

If a menu title is set, the platform will automatically add a menu item to the reporting menu. Alternatively, this behavior can be overwritten in configureReportingMenu().

Signature

  • It is a string value.

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

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

$orderOfReports

Signature

  • It is a array 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.

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

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.

configureWidget()

By default a widget will be configured for this report if a $widgetTitle is set.

If you want to customize the way the widget is added or modify any other behavior you can overwrite this method.

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

configureReportingMenu()

By default a menu item will be added to the reporting menu if a $menuTitle is set.

If you want to customize the way the item is added or modify any other behavior you can overwrite this method. For instance in case you need to add additional url properties beside module and action which are added by default.

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

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

getAllMetrics()

Returns the array of all metrics displayed by this report.

Signature

  • It returns a array value.

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 he visits 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 Piwik core. $infos contains the current requested date, period and site.

Signature

  • It accepts the following parameter(s):

    • $availableReports (Piwik\Plugin\$availableReports) —

    • $infos (Piwik\Plugin\$infos) —

  • It does not return anything.

getDocumentation()

Get report documentation.

Signature

  • It returns a string value.

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

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.

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.

factory()

Get an instance of a specific report belonging to the given module and having the given action.

Signature

  • It accepts the following parameter(s):

    • $module (string) —

    • $action (string) —

  • Returns: null|Report

getAllReports()

Returns a list of all available reports.

Even not enabled reports will be returned. They will be already sorted depending on the order and category of the report.

Signature

getAllReportClasses()

Returns class names of all Report metadata classes.

Signature

  • It returns a string[] 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