diff options
author | diosmosis <benaka@piwik.pro> | 2014-11-08 07:25:21 +0300 |
---|---|---|
committer | diosmosis <benaka@piwik.pro> | 2014-11-08 07:25:21 +0300 |
commit | 41f6d051a3c6a4083a807acdea4e681a02f8f9cb (patch) | |
tree | 5dd88b53e4f6b7ac81ea75d166b006aef69613a7 /core/Plugin/Metric.php | |
parent | 97dc9e2897fd5d365926af05078cf4f9941dd01a (diff) |
Documented Metric class and fixed regression in last commit's refactor.
Diffstat (limited to 'core/Plugin/Metric.php')
-rw-r--r-- | core/Plugin/Metric.php | 85 |
1 files changed, 51 insertions, 34 deletions
diff --git a/core/Plugin/Metric.php b/core/Plugin/Metric.php index af4fbcb9c4..8b2c9f7020 100644 --- a/core/Plugin/Metric.php +++ b/core/Plugin/Metric.php @@ -11,49 +11,53 @@ use Piwik\DataTable\Row; use Piwik\Metrics; /** - * TODO + * Base type of metric metadata classes. * - * TODO: note that this will be filled out in another issue + * 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 Report components are stored. + * The sub-namespace name in a plugin where Metric components are stored. */ const COMPONENT_SUBNAMESPACE = 'Metrics'; /** - * TODO + * Returns the column name of this metric, eg, `"nb_visits"` or `"avg_time_on_site"`. * - * @return Metric[] - */ - public static function getAll() - { - $components = Manager::getInstance()->findMultipleComponents(self::COMPONENT_SUBNAMESPACE, __CLASS__); - - $result = array(); - foreach ($components as $componentClass) { - /** @var Metric $component */ - $component = new $componentClass(); - - $name = $component->getName(); - $result[$name] = $component; - } - return $result; - } - - /** - * TODO + * This string is what appears in API output. + * + * @return string */ abstract public function getName(); /** - * TODO + * 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(); /** - * TODO + * 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() { @@ -61,7 +65,13 @@ abstract class Metric } /** - * TODO + * 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. + * + * @return mixed $value */ public function format($value) { @@ -69,27 +79,34 @@ abstract class Metric } /** - * TODO + * 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, $mappingIdToName = null) + public static function getMetric($row, $columnName, $mappingNameToId = null) { if (empty($mappingIdToName)) { - $mappingIdToName = Metrics::getMappingFromNameToId(); + $mappingNameToId = Metrics::getMappingFromNameToId(); } if ($row instanceof Row) { // TODO: benchmark w/ array-access (so we don't need this if statement). $value = $row->getColumn($columnName); if ($value === false - && isset($mappingIdToName[$columnName]) + && isset($mappingNameToId[$columnName]) ) { - $value = $row->getColumn($mappingIdToName[$columnName]); + $value = $row->getColumn($mappingNameToId[$columnName]); } } else { - $value = $row[$columnName]; + $value = @$row[$columnName]; if ($value === false - && isset($mappingIdToName[$columnName]) + && isset($mappingNameToId[$columnName]) ) { - $value = $row[$mappingIdToName[$columnName]]; + $value = $row[$mappingNameToId[$columnName]]; } return $value; } |