1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<?php
/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*/
namespace Piwik\Plugin;
use Piwik\DataTable;
use Piwik\DataTable\Row;
use Piwik\Metrics;
use Piwik\Metrics\Formatter;
/**
* 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 {@link Piwik\Plugin\ProcessedMetric} and {@link Piwik\Plugin|AggregatedMetric}.
*
* @api
*/
abstract class Metric
{
/**
* The sub-namespace name in a plugin where Metric components are stored.
*/
const COMPONENT_SUBNAMESPACE = 'Metrics';
/**
* Returns the column name of this metric, eg, `"nb_visits"` or `"avg_time_on_site"`.
*
* This string is what appears in API output.
*
* @return string
*/
abstract public function getName();
/**
* Returns the human readable translated name of this metric, eg, `"Visits"` or `"Avg. time on site"`.
*
* This string is what appears in the UI.
*
* @return string
*/
abstract public function getTranslatedName();
/**
* Returns the category that this metric belongs to.
* @return string
* @api since Piwik 3.2.0
*/
public function getCategoryId()
{
return '';
}
/**
* 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.
*
* @return string
*/
public function getDocumentation()
{
return "";
}
/**
* Returns a formatted metric value. This value is what appears in API output. From within 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.
*
* @param mixed $value The metric value.
* @param Formatter $formatter The formatter to use when formatting a value.
* @return mixed $value
*/
public function format($value, Formatter $formatter)
{
return $value;
}
/**
* 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).
*
* @param Report $report
* @param DataTable $table
* @return bool Return `true` to format the metric for the table, `false` to skip formatting.
*/
public function beforeFormat($report, DataTable $table)
{
return true;
}
/**
* Helper method that will access a metric in a {@link Piwik\DataTable\Row} or array either by
* its name or by its special numerical index value.
*
* @param Row|array $row
* @param string $columnName
* @param int[]|null $mappingNameToId A custom mapping of metric names to special index values. By
* default {@link Metrics::getMappingFromNameToId()} is used.
* @return mixed The metric value or false if none exists.
*/
public static function getMetric($row, $columnName, $mappingNameToId = null)
{
if ($row instanceof Row) {
$value = $row->getColumn($columnName);
if ($value === false) {
if (empty($mappingNameToId)) {
$mappingNameToId = Metrics::getMappingFromNameToId();
}
if (isset($mappingNameToId[$columnName])) {
return $row->getColumn($mappingNameToId[$columnName]);
}
}
return $value;
} elseif (!empty($row)) {
if (array_key_exists($columnName, $row)) {
return $row[$columnName];
} else {
if (empty($mappingNameToId)) {
$mappingNameToId = Metrics::getMappingFromNameToId();
}
if (isset($mappingNameToId[$columnName])) {
$columnName = $mappingNameToId[$columnName];
if (array_key_exists($columnName, $row)) {
return $row[$columnName];
}
}
}
}
return null;
}
/**
* Helper method that will determine the actual column name for a metric in a
* {@link Piwik\DataTable} and return every column value for this name.
*
* @param DataTable $table
* @param string $columnName
* @param int[]|null $mappingNameToId A custom mapping of metric names to special index values. By
* default {@link Metrics::getMappingFromNameToId()} is used.
* @return array
*/
public static function getMetricValues(DataTable $table, $columnName, $mappingNameToId = null)
{
if (empty($mappingIdToName)) {
$mappingNameToId = Metrics::getMappingFromNameToId();
}
$columnName = self::getActualMetricColumn($table, $columnName, $mappingNameToId);
return $table->getColumn($columnName);
}
/**
* Helper method that determines the actual column for a metric in a {@link Piwik\DataTable}.
*
* @param DataTable $table
* @param string $columnName
* @param int[]|null $mappingNameToId A custom mapping of metric names to special index values. By
* default {@link Metrics::getMappingFromNameToId()} is used.
* @return string
*/
public static function getActualMetricColumn(DataTable $table, $columnName, $mappingNameToId = null)
{
$firstRow = $table->getFirstRow();
if (!empty($firstRow) && $firstRow->hasColumn($columnName) === false) {
if (empty($mappingIdToName)) {
$mappingNameToId = Metrics::getMappingFromNameToId();
}
if (array_key_exists($columnName, $mappingNameToId)) {
$columnName = $mappingNameToId[$columnName];
}
}
return $columnName;
}
}
|
