API Reference

EvolutionMetric

Piwik\Plugins\CoreHome\Columns\Metrics\

EvolutionMetric

Calculates evolution values for any other metric.

(current value - value in past) / value in past

Methods

The class defines the following methods:

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.

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.

__construct()

Constructor.

Signature

  • It accepts the following parameter(s):
    • $wrapped (string|Metric) — The metric used to calculate the evolution.
    • $pastData (DataTable|null) — The data in the past to use when calculating evolutions.
    • $evolutionMetricName (string|false) — The name of the evolution processed metric. Defaults to $wrapped's name with '_evolution' appended.
    • $quotientPrecision (int) — The percent's quotient precision.
    • $currentData (DataTable|null) — The current datatable, optional but required to calculate the proportionate evolution values

getTrendName()

Signature

  • It does not return anything or a mixed result.

getTrendValue()

Signature

  • It accepts the following parameter(s):

    • $computedValue

  • It does not return anything or a mixed result.

beforeComputeSubtable()

Signature

  • It accepts the following parameter(s):

    • $row (Row) —

  • It does not return anything or a mixed result.

afterComputeSubtable()

Signature

  • It accepts the following parameter(s):

    • $row (Row) —

  • It does not return anything or a mixed result.

getPastRowFromCurrent()

public for Insights use.

Signature

  • It accepts the following parameter(s):

    • $row (Row) —

  • It does not return anything or a mixed result.

getRatio()

Calculate the ratio of time between a past period and current incomplete period

eg. if today is Thursday at 12:00pm and the past period is a week then the ratio is 0.5, exactly half of the current incomplete period has passed

If the current period end is in the past then the ratio will always be 1, since the current period is complete.

Signature

  • It accepts the following parameter(s):

  • Returns: float|int —

  • It throws one of the following exceptions: