Keep BC w/ old Formatter class since it is likely used by 3rd party plugins. Move Numeric formatter to CoreVisualizations and do not mark w/ @api.

4 files changed, 217 insertions, 324 deletions

diff --git a/core/Metrics/Formatter.php b/core/Metrics/Formatter.php
index 2c39d4a7f7..bce37e3be4 100644
--- a/core/Metrics/Formatter.php
+++ b/core/Metrics/Formatter.php
@@ -7,71 +7,228 @@
  */
 namespace Piwik\Metrics;
 
+use Piwik\Common;
+use Piwik\Container\StaticContainer;
 use Piwik\DataTable;
+use Piwik\Intl\Data\Provider\CurrencyDataProvider;
+use Piwik\Piwik;
 use Piwik\Plugin\Metric;
 use Piwik\Plugin\ProcessedMetric;
 use Piwik\Plugin\Report;
+use Piwik\Site;
+use Piwik\Tracker\GoalManager;
 
 /**
  * Contains methods to format metric values. Passed to the {@link \Piwik\Plugin\Metric::format()}
  * method when formatting Metrics.
- *
- * @api
  */
-abstract class Formatter
+class Formatter
 {
     const PROCESSED_METRICS_FORMATTED_FLAG = 'processed_metrics_formatted';
 
+    private $decimalPoint = null;
+    private $thousandsSeparator = null;
+
     /**
-     * Returns a prettified, rounded number.
+     * Returns a prettified string representation of a number. The result will have
+     * thousands separators and a decimal point specific to the current locale, eg,
+     * `'1,000,000.05'` or `'1.000.000,05'`.
      *
-     * @param int|float $value
-     * @param int $precision
-     * @return int|float|string
+     * @param number $value
+     * @return string
+     * @api
      */
-    public abstract function getPrettyNumber($value, $precision = 0);
+    public function getPrettyNumber($value, $precision = 0)
+    {
+        if ($this->decimalPoint === null) {
+            $locale = localeconv();
+
+            $this->decimalPoint = $locale['decimal_point'];
+            $this->thousandsSeparator = $locale['thousands_sep'];
+        }
+
+        return number_format($value, $precision, $this->decimalPoint, $this->thousandsSeparator);
+    }
 
     /**
-     * Returns a pretty formatted time value.
+     * Returns a prettified time value (in seconds).
      *
-     * @param int|float $numberOfSeconds The seconds value to format.
-     * @param bool $displayTimeAsSentence If true, the formatter might return the number w/ words
-     *                                    and numbers. The formatter may ignore this value as well,
-     *                                    depending on the context.
-     * @param bool $round If true, the number of seconds is rounded, otherwise the result will contain
-     *                    a floating point.
-     * @return int|float|string
+     * @param int $numberOfSeconds The number of seconds.
+     * @param bool $displayTimeAsSentence If set to true, will output `"5min 17s"`, if false `"00:05:17"`.
+     * @param bool $round Whether to round to the nearest second or not.
+     * @return string
+     * @api
      */
-    public abstract function getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence = false, $round = false);
+    public function getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence = false, $round = false)
+    {
+        $numberOfSeconds = $round ? (int)$numberOfSeconds : (float)$numberOfSeconds;
+
+        $isNegative = false;
+        if ($numberOfSeconds < 0) {
+            $numberOfSeconds = -1 * $numberOfSeconds;
+            $isNegative = true;
+        }
+
+        // Display 01:45:17 time format
+        if ($displayTimeAsSentence === false) {
+            $hours   = floor($numberOfSeconds / 3600);
+            $minutes = floor(($reminder = ($numberOfSeconds - $hours * 3600)) / 60);
+            $seconds = floor($reminder - $minutes * 60);
+            $time    = sprintf("%02s", $hours) . ':' . sprintf("%02s", $minutes) . ':' . sprintf("%02s", $seconds);
+            $centiSeconds = ($numberOfSeconds * 100) % 100;
+            if ($centiSeconds) {
+                $time .= '.' . sprintf("%02s", $centiSeconds);
+            }
+            if ($isNegative) {
+                $time = '-' . $time;
+            }
+            return $time;
+        }
+        $secondsInYear = 86400 * 365.25;
+
+        $years      = floor($numberOfSeconds / $secondsInYear);
+        $minusYears = $numberOfSeconds - $years * $secondsInYear;
+        $days       = floor($minusYears / 86400);
+
+        $minusDays = $numberOfSeconds - $days * 86400;
+        $hours     = floor($minusDays / 3600);
+
+        $minusDaysAndHours = $minusDays - $hours * 3600;
+        $minutes = floor($minusDaysAndHours / 60);
+
+        $seconds   = $minusDaysAndHours - $minutes * 60;
+        $precision = ($seconds > 0 && $seconds < 0.01 ? 3 : 2);
+        $seconds   = round($seconds, $precision);
+
+        if ($years > 0) {
+            $return = sprintf(Piwik::translate('General_YearsDays'), $years, $days);
+        } elseif ($days > 0) {
+            $return = sprintf(Piwik::translate('General_DaysHours'), $days, $hours);
+        } elseif ($hours > 0) {
+            $return = sprintf(Piwik::translate('General_HoursMinutes'), $hours, $minutes);
+        } elseif ($minutes > 0) {
+            $return = sprintf(Piwik::translate('General_MinutesSeconds'), $minutes, $seconds);
+        } else {
+            $return = sprintf(Piwik::translate('General_Seconds'), $seconds);
+        }
+
+        if ($isNegative) {
+            $return = '-' . $return;
+        }
+
+        return $return;
+    }
 
     /**
-     * Returns the prettified byte size value.
+     * Returns a prettified memory size value.
      *
-     * @param int $size
-     * @param string|null $unit A specific unit to format as, or null to use the biggest one that
-     *                          results in a value greater than 1. Supported units include:
-     *                          `'B', 'K', 'M', 'G', 'T'`
-     * @param int $precision
-     * @return int|float|string
+     * @param number $size The size in bytes.
+     * @param string $unit The specific unit to use, if any. If null, the unit is determined by $size.
+     * @param int $precision The precision to use when rounding.
+     * @return string eg, `'128 M'` or `'256 K'`.
+     * @api
      */
-    public abstract function getPrettySizeFromBytes($size, $unit = null, $precision = 1);
+    public function getPrettySizeFromBytes($size, $unit = null, $precision = 1)
+    {
+        if ($size == 0) {
+            return '0 M';
+        }
+
+        list($size, $sizeUnit) = $this->getPrettySizeFromBytesWithUnit($size, $unit, $precision);
+        return $size . " " . $sizeUnit;
+    }
 
     /**
-     * Returns a pretty formatted money value using a site's currency.
+     * Returns a pretty formated monetary value using the currency associated with a site.
      *
-     * @param int|float $value
-     * @param int $idSite
-     * @return int|float|string
+     * @param int|string $value The monetary value to format.
+     * @param int $idSite The ID of the site whose currency will be used.
+     * @return string
+     * @api
      */
-    public abstract function getPrettyMoney($value, $idSite);
+    public function getPrettyMoney($value, $idSite)
+    {
+        $space = ' ';
+
+        $currencySymbol = self::getCurrencySymbol($idSite);
+
+        $currencyBefore =  $currencySymbol . $space;
+        $currencyAfter = '';
+
+        // (maybe more currencies prefer this notation?)
+        $currencySymbolToAppend = array('€', 'kr', 'zł');
+
+        // manually put the currency symbol after the amount
+        if (in_array($currencySymbol, $currencySymbolToAppend)) {
+            $currencyAfter = $space . $currencySymbol;
+            $currencyBefore = '';
+        }
+
+        // if the input is a number (it could be a string or INPUT form),
+        // and if this number is not an int, we round to precision 2
+        if (is_numeric($value)) {
+            if ($value == round($value)) {
+                // 0.0 => 0
+                $value = round($value);
+            } else {
+                $precision = GoalManager::REVENUE_PRECISION;
+                $value = sprintf("%01." . $precision . "f", $value);
+            }
+        }
+
+        $prettyMoney = $currencyBefore . $value . $currencyAfter;
+        return $prettyMoney;
+    }
 
     /**
-     * Returns a pretty formatted percent value from a quotient value.
+     * Returns a percent string from a quotient value. Forces the use of a '.'
+     * decimal place.
      *
      * @param float $value
-     * @return int|float|string
+     * @return string
+     * @api
      */
-    public abstract function getPrettyPercentFromQuotient($value);
+    public function getPrettyPercentFromQuotient($value)
+    {
+        $result = ($value * 100) . '%';
+        return Common::forceDotAsSeparatorForDecimalPoint($result);
+    }
+
+    /**
+     * Returns the currency symbol for a site.
+     *
+     * @param int $idSite The ID of the site to return the currency symbol for.
+     * @return string eg, `'$'`.
+     * @api
+     */
+    public static function getCurrencySymbol($idSite)
+    {
+        $symbols  = self::getCurrencyList();
+        $currency = Site::getCurrencyFor($idSite);
+
+        if (isset($symbols[$currency])) {
+            return $symbols[$currency][0];
+        }
+
+        return '';
+    }
+
+    /**
+     * Returns the list of all known currency symbols.
+     *
+     * @return array An array mapping currency codes to their respective currency symbols
+     *               and a description, eg, `array('USD' => array('$', 'US dollar'))`.
+     *
+     * @deprecated Use Piwik\Intl\Data\Provider\CurrencyDataProvider instead.
+     * @see \Piwik\Intl\Data\Provider\CurrencyDataProvider::getCurrencyList()
+     * @api
+     */
+    public static function getCurrencyList()
+    {
+        /** @var CurrencyDataProvider $dataProvider */
+        $dataProvider = StaticContainer::get('Piwik\Intl\Data\Provider\CurrencyDataProvider');
+        return $dataProvider->getCurrencyList();
+    }
 
     /**
      * Formats all metrics, including processed metrics, for a DataTable. Metrics to format
@@ -80,6 +237,7 @@ abstract class Formatter
      * @param DataTable $dataTable The table to format metrics for.
      * @param Report|null $report The report the table belongs to.
      * @param string[]|null $metricsToFormat Whitelist of names of metrics to format.
+     * @api
      */
     public function formatMetrics(DataTable $dataTable, Report $report = null, $metricsToFormat = null)
     {
@@ -118,6 +276,29 @@ abstract class Formatter
         }
     }
 
+    protected function getPrettySizeFromBytesWithUnit($size, $unit = null, $precision = 1)
+    {
+        $units = array('B', 'K', 'M', 'G', 'T');
+        $numUnits = count($units) - 1;
+
+        $currentUnit = null;
+        foreach ($units as $idx => $currentUnit) {
+            if ($unit && $unit !== $currentUnit) {
+                $size = $size / 1024;
+            } elseif ($unit && $unit === $currentUnit) {
+                break;
+            } elseif ($size >= 1024 && $idx != $numUnits) {
+                $size = $size / 1024;
+            } else {
+                break;
+            }
+        }
+
+        $size = round($size, $precision);
+
+        return array($size, $currentUnit);
+    }
+
     private function makeRegexToMatchMetrics($metricsToFormat)
     {
         $metricsRegexParts = array();
diff --git a/core/Metrics/Formatter/Api.php b/core/Metrics/Formatter/Api.php
deleted file mode 100644
index 1fc916d961..0000000000
--- a/core/Metrics/Formatter/Api.php
+++ /dev/null
@@ -1,221 +0,0 @@
-<?php
-/**
- * Piwik - free/libre analytics platform
- *
- * @link http://piwik.org
- * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
- */
-
-namespace Piwik\Metrics\Formatter;
-
-use Piwik\Common;
-use Piwik\Container\StaticContainer;
-use Piwik\Intl\Data\Provider\CurrencyDataProvider;
-use Piwik\Piwik;
-use Piwik\Site;
-use Piwik\Tracker\GoalManager;
-
-/**
- * TODO
- *
- * @api
- */
-class Api extends Numeric
-{
-    private $decimalPoint = null;
-    private $thousandsSeparator = null;
-
-    /**
-     * Returns a prettified string representation of a number. The result will have
-     * thousands separators and a decimal point specific to the current locale, eg,
-     * `'1,000,000.05'` or `'1.000.000,05'`.
-     *
-     * @param number $value
-     * @return string
-     */
-    public function getPrettyNumber($value, $precision = 0)
-    {
-        if ($this->decimalPoint === null) {
-            $locale = localeconv();
-
-            $this->decimalPoint = $locale['decimal_point'];
-            $this->thousandsSeparator = $locale['thousands_sep'];
-        }
-
-        return number_format($value, $precision, $this->decimalPoint, $this->thousandsSeparator);
-    }
-
-    /**
-     * Returns a prettified time value (in seconds).
-     *
-     * @param int $numberOfSeconds The number of seconds.
-     * @param bool $displayTimeAsSentence If set to true, will output `"5min 17s"`, if false `"00:05:17"`.
-     * @param bool $round Whether to round to the nearest second or not.
-     * @return string
-     */
-    public function getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence = false, $round = false)
-    {
-        $numberOfSeconds = parent::getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence, $round);
-
-        $isNegative = false;
-        if ($numberOfSeconds < 0) {
-            $numberOfSeconds = -1 * $numberOfSeconds;
-            $isNegative = true;
-        }
-
-        // Display 01:45:17 time format
-        if ($displayTimeAsSentence === false) {
-            $hours   = floor($numberOfSeconds / 3600);
-            $minutes = floor(($reminder = ($numberOfSeconds - $hours * 3600)) / 60);
-            $seconds = floor($reminder - $minutes * 60);
-            $time    = sprintf("%02s", $hours) . ':' . sprintf("%02s", $minutes) . ':' . sprintf("%02s", $seconds);
-            $centiSeconds = ($numberOfSeconds * 100) % 100;
-            if ($centiSeconds) {
-                $time .= '.' . sprintf("%02s", $centiSeconds);
-            }
-            if ($isNegative) {
-                $time = '-' . $time;
-            }
-            return $time;
-        }
-        $secondsInYear = 86400 * 365.25;
-
-        $years      = floor($numberOfSeconds / $secondsInYear);
-        $minusYears = $numberOfSeconds - $years * $secondsInYear;
-        $days       = floor($minusYears / 86400);
-
-        $minusDays = $numberOfSeconds - $days * 86400;
-        $hours     = floor($minusDays / 3600);
-
-        $minusDaysAndHours = $minusDays - $hours * 3600;
-        $minutes = floor($minusDaysAndHours / 60);
-
-        $seconds   = $minusDaysAndHours - $minutes * 60;
-        $precision = ($seconds > 0 && $seconds < 0.01 ? 3 : 2);
-        $seconds   = round($seconds, $precision);
-
-        if ($years > 0) {
-            $return = sprintf(Piwik::translate('General_YearsDays'), $years, $days);
-        } elseif ($days > 0) {
-            $return = sprintf(Piwik::translate('General_DaysHours'), $days, $hours);
-        } elseif ($hours > 0) {
-            $return = sprintf(Piwik::translate('General_HoursMinutes'), $hours, $minutes);
-        } elseif ($minutes > 0) {
-            $return = sprintf(Piwik::translate('General_MinutesSeconds'), $minutes, $seconds);
-        } else {
-            $return = sprintf(Piwik::translate('General_Seconds'), $seconds);
-        }
-
-        if ($isNegative) {
-            $return = '-' . $return;
-        }
-
-        return $return;
-    }
-
-    /**
-     * Returns a prettified memory size value.
-     *
-     * @param number $size The size in bytes.
-     * @param string $unit The specific unit to use, if any. If null, the unit is determined by $size.
-     * @param int $precision The precision to use when rounding.
-     * @return string eg, `'128 M'` or `'256 K'`.
-     */
-    public function getPrettySizeFromBytes($size, $unit = null, $precision = 1)
-    {
-        if ($size == 0) {
-            return '0 M';
-        }
-
-        list($size, $sizeUnit) = $this->getPrettySizeFromBytesWithUnit($size, $unit, $precision);
-        return $size . " " . $sizeUnit;
-    }
-
-    /**
-     * Returns a pretty formated monetary value using the currency associated with a site.
-     *
-     * @param int|string $value The monetary value to format.
-     * @param int $idSite The ID of the site whose currency will be used.
-     * @return string
-     */
-    public function getPrettyMoney($value, $idSite)
-    {
-        $space = ' ';
-
-        $currencySymbol = self::getCurrencySymbol($idSite);
-
-        $currencyBefore =  $currencySymbol . $space;
-        $currencyAfter = '';
-
-        // (maybe more currencies prefer this notation?)
-        $currencySymbolToAppend = array('€', 'kr', 'zł');
-
-        // manually put the currency symbol after the amount
-        if (in_array($currencySymbol, $currencySymbolToAppend)) {
-            $currencyAfter = $space . $currencySymbol;
-            $currencyBefore = '';
-        }
-
-        // if the input is a number (it could be a string or INPUT form),
-        // and if this number is not an int, we round to precision 2
-        if (is_numeric($value)) {
-            if ($value == round($value)) {
-                // 0.0 => 0
-                $value = round($value);
-            } else {
-                $precision = GoalManager::REVENUE_PRECISION;
-                $value = sprintf("%01." . $precision . "f", $value);
-            }
-        }
-
-        $prettyMoney = $currencyBefore . $value . $currencyAfter;
-        return $prettyMoney;
-    }
-
-    /**
-     * Returns a percent string from a quotient value. Forces the use of a '.'
-     * decimal place.
-     *
-     * @param float $value
-     * @return string
-     */
-    public function getPrettyPercentFromQuotient($value)
-    {
-        $result = parent::getPrettyPercentFromQuotient($value) . '%';
-        return Common::forceDotAsSeparatorForDecimalPoint($result);
-    }
-
-    /**
-     * Returns the currency symbol for a site.
-     *
-     * @param int $idSite The ID of the site to return the currency symbol for.
-     * @return string eg, `'$'`.
-     */
-    public static function getCurrencySymbol($idSite)
-    {
-        $symbols  = self::getCurrencyList();
-        $currency = Site::getCurrencyFor($idSite);
-
-        if (isset($symbols[$currency])) {
-            return $symbols[$currency][0];
-        }
-
-        return '';
-    }
-
-    /**
-     * Returns the list of all known currency symbols.
-     *
-     * @return array An array mapping currency codes to their respective currency symbols
-     *               and a description, eg, `array('USD' => array('$', 'US dollar'))`.
-     *
-     * @deprecated Use Piwik\Intl\Data\Provider\CurrencyDataProvider instead.
-     * @see \Piwik\Intl\Data\Provider\CurrencyDataProvider::getCurrencyList()
-     */
-    public static function getCurrencyList()
-    {
-        /** @var CurrencyDataProvider $dataProvider */
-        $dataProvider = StaticContainer::get('Piwik\Intl\Data\Provider\CurrencyDataProvider');
-        return $dataProvider->getCurrencyList();
-    }
-}
\ No newline at end of file
diff --git a/core/Metrics/Formatter/Html.php b/core/Metrics/Formatter/Html.php
index f8f575f831..c4f9e05664 100644
--- a/core/Metrics/Formatter/Html.php
+++ b/core/Metrics/Formatter/Html.php
@@ -7,11 +7,13 @@
  */
 namespace Piwik\Metrics\Formatter;
 
+use Piwik\Metrics\Formatter;
+
 /**
  * Metrics formatter that formats for HTML output. Uses non-breaking spaces in formatted values
  * so text will stay unbroken in HTML views.
  */
-class Html extends Api
+class Html extends Formatter
 {
     public function getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence = true, $round = false)
     {
diff --git a/core/Metrics/Formatter/Numeric.php b/core/Metrics/Formatter/Numeric.php
deleted file mode 100644
index 225e026e7b..0000000000
--- a/core/Metrics/Formatter/Numeric.php
+++ /dev/null
@@ -1,69 +0,0 @@
-<?php
-/**
- * Piwik - free/libre analytics platform
- *
- * @link http://piwik.org
- * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
- */
-namespace Piwik\Metrics\Formatter;
-
-use Piwik\Metrics\Formatter;
-
-/**
- * A metrics formatter that prettifies metric values without returning string values.
- * Results of this class can be converted to numeric values and processed further in
- * some way.
- *
- * @api
- */
-class Numeric extends Formatter
-{
-    public function getPrettyNumber($value, $precision = 0)
-    {
-        return round($value, $precision);
-    }
-
-    public function getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence = false, $round = false)
-    {
-        return $round ? (int)$numberOfSeconds : (float)$numberOfSeconds;
-    }
-
-    public function getPrettySizeFromBytes($size, $unit = null, $precision = 1)
-    {
-        list($size, $sizeUnit) = $this->getPrettySizeFromBytesWithUnit($size, $unit, $precision);
-        return $size;
-    }
-
-    protected function getPrettySizeFromBytesWithUnit($size, $unit = null, $precision = 1)
-    {
-        $units = array('B', 'K', 'M', 'G', 'T');
-        $numUnits = count($units) - 1;
-
-        $currentUnit = null;
-        foreach ($units as $idx => $currentUnit) {
-            if ($unit && $unit !== $currentUnit) {
-                $size = $size / 1024;
-            } elseif ($unit && $unit === $currentUnit) {
-                break;
-            } elseif ($size >= 1024 && $idx != $numUnits) {
-                $size = $size / 1024;
-            } else {
-                break;
-            }
-        }
-
-        $size = round($size, $precision);
-
-        return array($size, $currentUnit);
-    }
-
-    public function getPrettyMoney($value, $idSite)
-    {
-        return $value;
-    }
-
-    public function getPrettyPercentFromQuotient($value)
-    {
-        return $value * 100;
-    }
-}
\ No newline at end of file