Piwik\Plugin\

ProcessedMetric

Base type for processed metrics.

A processed metric is a metric that is computed using one or more other metrics.

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". Inherited from Metric
  • getTranslatedName() ash; Returns the human readable translated name of this metric, eg, "Visits" or "Avg. Inherited from [Metric`](../../Piwik/Plugin/Metric.md)
  • getCategoryId() ash; Returns the category that this metric belongs to. Inherited from Metric
  • getDocumentation() ash; Returns a string describing what the metric represents. Inherited from Metric
  • format() ash; Returns a formatted metric value. Inherited from Metric
  • beforeFormat() ash; Executed before formatting all metrics for a report. Inherited from Metric
  • 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. Inherited from Metric
  • 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. Inherited from Metric
  • getActualMetricColumn() ash; Helper method that determines the actual column for a metric in a DataTable. Inherited from Metric
  • compute() ash; Computes the metric using the values in a Row.
  • getDependentMetrics() — Returns the array of metrics that are necessary for computing this metric.
  • getTemporaryMetrics() — Returns the array of metrics that are necessary for computing this metric, but should not be displayed to the user unless explicitly requested.
  • beforeCompute() — Executed before computing all processed metrics for a report.

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 does not return anything.

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.

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.

compute()

Computes the metric using the values in a Row.

The computed value should be numerical and not formatted in any way. For example, for a percent value, 0.14 should be returned instead of "14%".

Signature

  • It accepts the following parameter(s):

    • $row (Row) —
  • It returns a mixed value.

getDependentMetrics()

Returns the array of metrics that are necessary for computing this metric.

The elements of the array are metric names.

Signature

  • It returns a string[] value.

getTemporaryMetrics()

Returns the array of metrics that are necessary for computing this metric, but should not be displayed to the user unless explicitly requested.

These metrics are intermediate metrics that are not really valuable to the user. On a request, if showColumns or hideColumns is not used, they will be removed automatically.

Signature

  • It returns a string[] value.

beforeCompute()

Executed before computing all processed metrics for a report.

Implementers can return false to skip computing this metric.

Signature

  • It accepts the following parameter(s):

  • Returns: bool — Return true to compute the metric for the table, false to skip computing this metric.