API Reference

Metric

Piwik\Plugin\

Metric

Base type of metric metadata classes.

A metric metadata class is a class that describes how a metric is described, computed and formatted.

There are two types of metrics: aggregated and processed. An aggregated metric is computed in the backend datastore and aggregated in PHP when archiving period reports.

Currently, only processed metrics can be defined as metric metadata classes. Support for aggregated metrics will be added at a later date.

See ProcessedMetric and Piwik\Plugin|AggregatedMetric.

Methods

The abstract class defines the following methods:

  • getName() ash; Returns the column name of this metric, eg, "nb_visits" or "avg_time_on_site".
  • getTranslatedName() ash; Returns the human readable translated name of this metric, eg, "Visits" or `"Avg.
  • getCategoryId() — Returns the category that this metric belongs to.
  • getDocumentation() — Returns a string describing what the metric represents.
  • getSemanticType() — Returns this metric's semantic type.
  • format() — Returns a formatted metric value.
  • beforeFormat() — Executed before formatting all metrics for a report.
  • getMetric() ash; Helper method that will access a metric in a Row or array either by its name or by its special numerical index value.
  • getMetricValues() ash; Helper method that will determine the actual column name for a metric in a DataTable and return every column value for this name.
  • getActualMetricColumn() ash; Helper method that determines the actual column for a metric in a DataTable.

getName()

Returns the column name of this metric, eg, "nb_visits" or "avg_time_on_site".

This string is what appears in API output.

Signature

  • It returns a string value.

getTranslatedName()

Returns the human readable translated name of this metric, eg, "Visits" or "Avg. time on site".

This string is what appears in the UI.

Signature

  • It returns a string value.

getCategoryId()

Returns the category that this metric belongs to.

Signature

  • It returns a string value.

getDocumentation()

Returns a string describing what the metric represents. The result will be included in report metadata API output, including processed reports.

Implementing this method is optional.

Signature

  • It returns a string value.

getSemanticType()

Returns this metric's semantic type. This can be used to provide the semantic type for processed metrics.

A metric's semantic type is metadata used primarily in integrations with Matomo and third party services/applications. It provides information that can be used to determine how to display or use the information.

It is recommended for your plugin to provide this information so users of third party services that connect with Matomo can make full use of the data your plugin tracks.

See Dimension for the list of available semantic types.

Signature

  • Returns: string|null —

format()

Returns a formatted metric value. This value is what appears in API output. From within Matomo (formerly Piwik), (core & plugins) the computed value is used. Only when outputting to the API does a metric get formatted.

By default, just returns the value.

Signature

  • It accepts the following parameter(s):

    • $value (mixed) — The metric value.
    • $formatter (Formatter) — The formatter to use when formatting a value.

  • Returns: mixed — $value

beforeFormat()

Executed before formatting all metrics for a report. Implementers can return false to skip formatting this metric and can use this method to access information needed for formatting (for example, the site ID).

Signature

  • It accepts the following parameter(s):

  • Returns: bool — Return true to format the metric for the table, false to skip formatting.

getMetric()

Helper method that will access a metric in a Row or array either by its name or by its special numerical index value.

Signature

  • It accepts the following parameter(s):

    • $row (Row|array) —

    • $columnName (string) —

    • $mappingNameToId (int[]|null) — A custom mapping of metric names to special index values. By default Metrics::getMappingFromNameToId() is used.

  • Returns: mixed — The metric value or false if none exists.

getMetricValues()

Helper method that will determine the actual column name for a metric in a DataTable and return every column value for this name.

Signature

  • It accepts the following parameter(s):

    • $table (DataTable) —

    • $columnName (string) —

    • $mappingNameToId (int[]|null) — A custom mapping of metric names to special index values. By default Metrics::getMappingFromNameToId() is used.

  • It returns a array value.

getActualMetricColumn()

Helper method that determines the actual column for a metric in a DataTable.

Signature

  • It accepts the following parameter(s):

    • $table (DataTable) —

    • $columnName (string) —

    • $mappingNameToId (int[]|null) — A custom mapping of metric names to special index values. By default Metrics::getMappingFromNameToId() is used.

  • It returns a string value.