formatter WIP.

framework/yii/base/Formatter.php

+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\base;
+
+use Yii;
+use DateTime;
+use yii\helpers\HtmlPurifier;
+use yii\helpers\Html;
+
+
+/**
+ * Formatter provides a set of commonly used data formatting methods.
+ *
+ * The formatting methods provided by Formatter are all named in the form of `asXyz()`.
+ * The behavior of some of them may be configured via the properties of Formatter. For example,
+ * by configuring [[dateFormat]], one may control how [[asDate()]] formats the value into a date string.
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @since 2.0
+ */
+class Formatter extends Component
+{
+	/**
+	 * @var string the default format string to be used to format a date using PHP date() function.
+	 */
+	public $dateFormat = 'Y/m/d';
+	/**
+	 * @var string the default format string to be used to format a time using PHP date() function.
+	 */
+	public $timeFormat = 'h:i:s A';
+	/**
+	 * @var string the default format string to be used to format a date and time using PHP date() function.
+	 */
+	public $datetimeFormat = 'Y/m/d h:i:s A';
+	/**
+	 * @var array the format used to format a number with PHP number_format() function.
+	 * Three elements may be specified: "decimals", "decimalSeparator" and "thousandSeparator".
+	 * They correspond to the number of digits after the decimal point, the character displayed as the decimal point
+	 * and the thousands separator character.
+	 */
+	public $numberFormat = array('decimals' => null, 'decimalSeparator' => null, 'thousandSeparator' => null);
+	/**
+	 * @var array the text to be displayed when formatting a boolean value. The first element corresponds
+	 * to the text display for false, the second element for true. Defaults to <code>array('No', 'Yes')</code>.
+	 */
+	public $booleanFormat;
+
+
+	/**
+	 * Initializes the component.
+	 */
+	public function init()
+	{
+		if (empty($this->booleanFormat)) {
+			$this->booleanFormat = array(Yii::t('yii', 'No'), Yii::t('yii', 'Yes'));
+		}
+	}
+
+	/**
+	 * Formats the value as is without any formatting.
+	 * This method simply returns back the parameter without any format.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asRaw($value)
+	{
+		return $value;
+	}
+
+	/**
+	 * Formats the value as an HTML-encoded plain text.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asText($value)
+	{
+		return Html::encode($value);
+	}
+
+	/**
+	 * Formats the value as an HTML-encoded plain text with newlines converted into breaks.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asNtext($value)
+	{
+		return nl2br(Html::encode($value));
+	}
+
+	/**
+	 * Formats the value as HTML-encoded text paragraphs.
+	 * Each text paragraph is enclosed within a `<p>` tag.
+	 * One or multiple consecutive empty lines divide two paragraphs.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asParagraphs($value)
+	{
+		return str_replace('<p></p>', '',
+			'<p>' . preg_replace('/[\r\n]{2,}/', "</p>\n<p>", Html::encode($value)) . '</p>'
+		);
+	}
+
+	/**
+	 * Formats the value as HTML text.
+	 * The value will be purified using [[HtmlPurifier]] to avoid XSS attacks.
+	 * Use [[asRaw()]] if you do not want any purification of the value.
+	 * @param mixed $value the value to be formatted
+	 * @param array|null $config the configuration for the HTMLPurifier class.
+	 * @return string the formatted result
+	 */
+	public function asHtml($value, $config = null)
+	{
+		return HtmlPurifier::process($value, $config);
+	}
+
+	/**
+	 * Formats the value as a mailto link.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asEmail($value)
+	{
+		return Html::mailto($value);
+	}
+
+	/**
+	 * Formats the value as an image tag.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asImage($value)
+	{
+		return Html::img($value);
+	}
+
+	/**
+	 * Formats the value as a hyperlink.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 */
+	public function asUrl($value)
+	{
+		$url = $value;
+		if (strpos($url, 'http://') !== 0 && strpos($url, 'https://') !== 0) {
+			$url = 'http://' . $url;
+		}
+		return Html::a(Html::encode($value), $url);
+	}
+
+	/**
+	 * Formats the value as a boolean.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatted result
+	 * @see booleanFormat
+	 */
+	public function asBoolean($value)
+	{
+		return $value ? $this->booleanFormat[1] : $this->booleanFormat[0];
+	}
+
+	/**
+	 * Formats the value as a date.
+	 * @param integer|string|DateTime $value the value to be formatted. The following
+	 * types of value are supported:
+	 *
+	 * - an integer representing UNIX timestamp
+	 * - a string that can be parsed into a UNIX timestamp via `strtotime()`
+	 * - a PHP DateTime object
+	 *
+	 * @param string $format the format used to convert the value into a date string.
+	 * If null, [[dateFormat]] will be used. The format string should be the one
+	 * that can be recognized by the PHP `date()` function.
+	 * @return string the formatted result
+	 * @see dateFormat
+	 */
+	public function asDate($value, $format = null)
+	{
+		$value = $this->normalizeDatetimeValue($value);
+		return date($format === null ? $this->dateFormat : $format, $value);
+	}
+
+	/**
+	 * Formats the value as a time.
+	 * @param integer|string|DateTime $value the value to be formatted. The following
+	 * types of value are supported:
+	 *
+	 * - an integer representing UNIX timestamp
+	 * - a string that can be parsed into a UNIX timestamp via `strtotime()`
+	 * - a PHP DateTime object
+	 *
+	 * @param string $format the format used to convert the value into a date string.
+	 * If null, [[timeFormat]] will be used. The format string should be the one
+	 * that can be recognized by the PHP `date()` function.
+	 * @return string the formatted result
+	 * @see timeFormat
+	 */
+	public function asTime($value, $format = null)
+	{
+		$value = $this->normalizeDatetimeValue($value);
+		return date($format === null ? $this->timeFormat : $format, $value);
+	}
+
+	/**
+	 * Formats the value as a datetime.
+	 * @param integer|string|DateTime $value the value to be formatted. The following
+	 * types of value are supported:
+	 *
+	 * - an integer representing UNIX timestamp
+	 * - a string that can be parsed into a UNIX timestamp via `strtotime()`
+	 * - a PHP DateTime object
+	 *
+	 * @param string $format the format used to convert the value into a date string.
+	 * If null, [[datetimeFormat]] will be used. The format string should be the one
+	 * that can be recognized by the PHP `date()` function.
+	 * @return string the formatted result
+	 * @see datetimeFormat
+	 */
+	public function asDatetime($value, $format = null)
+	{
+		$value = $this->normalizeDatetimeValue($value);
+		return date($format === null ? $this->datetimeFormat : $format, $value);
+	}
+
+	/**
+	 * Normalizes the given datetime value as one that can be taken by various date/time formatting methods.
+	 * @param mixed $value the datetime value to be normalized.
+	 * @return mixed the normalized datetime value
+	 */
+	protected function normalizeDatetimeValue($value)
+	{
+		if (is_string($value)) {
+			if (ctype_digit($value) || $value[0] === '-' && ctype_digit(substr($value, 1))) {
+				return (int)$value;
+			} else {
+				return strtotime($value);
+			}
+		} elseif ($value instanceof DateTime) {
+			return $value->getTimestamp();
+		} else {
+			return (int)$value;
+		}
+	}
+
+	/**
+	 * Formats the value as an integer.
+	 * @param mixed $value the value to be formatted
+	 * @return string the formatting result.
+	 */
+	public function asInteger($value)
+	{
+		if (is_string($value) && preg_match('/^(-?\d+)/', $value, $matches)) {
+			return $matches[1];
+		} else {
+			$value = (int)$value;
+			return "$value";
+		}
+	}
+
+	/**
+	 * Formats the value as a double number.
+	 * @param mixed $value the value to be formatted
+	 * @param integer $decimals the number of digits after the decimal point
+	 * @return string the formatting result.
+	 */
+	public function asDouble($value, $decimals = 2)
+	{
+		return sprintf("%.{$decimals}f", $value);
+	}
+
+	/**
+	 * Formats the value as a decimal number using the PHP number_format() function.
+	 * @param mixed $value the value to be formatted
+	 * @param integer $decimals the number of digits after the decimal point
+	 * @param string $decimalSeparator the character displayed as the decimal point
+	 * @param string $thousandSeparator the character displayed as the thousands separator character.
+	 * @return string the formatted result
+	 */
+	public function asDecimal($value, $decimals = 0 , $decimalSeparator = '.' , $thousandSeparator = ',' )
+	{
+		return number_format($value, $decimals, $decimalSeparator, $thousandSeparator);
+	}
+}

framework/yii/i18n/Formatter.php

+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\i18n;
+
+use Yii;
+use IntlDateFormatter;
+use NumberFormatter;
+use DateTime;
+use yii\base\InvalidConfigException;
+
+/**
+ * Formatter is the localized version of [[\yii\base\Formatter]].
+ *
+ * Formatter requires the PHP "intl" extension to be installed. Formatter supports localized
+ * formatting of date, time and numbers, based on the current [[locale]].
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @since 2.0
+ */
+class Formatter extends \yii\base\Formatter
+{
+	/**
+	 * @var string the locale ID that is used to localize the date and number formatting.
+	 * If not set, [[\yii\base\Application::language]] will be used.
+	 */
+	public $locale;
+	/**
+	 * @var string the default format string to be used to format a date using PHP date() function.
+	 */
+	public $dateFormat = 'short';
+	/**
+	 * @var string the default format string to be used to format a time using PHP date() function.
+	 */
+	public $timeFormat = 'short';
+	/**
+	 * @var string the default format string to be used to format a date and time using PHP date() function.
+	 */
+	public $datetimeFormat = 'short';
+	/**
+	 * @var array the options to be set for the NumberFormatter objects. Please refer to
+	 */
+	public $numberFormatOptions = array();
+
+
+	/**
+	 * Initializes the component.
+	 * This method will check if the "intl" PHP extension is installed and set the
+	 * default value of [[locale]].
+	 * @throws InvalidConfigException if the "intl" PHP extension is not installed.
+	 */
+	public function init()
+	{
+		if (!extension_loaded('intl')) {
+			throw new InvalidConfigException('The "intl" PHP extension is not install. It is required to format data values in localized formats.');
+		}
+		if ($this->locale === null) {
+			$this->locale = Yii::$app->language;
+		}
+		parent::init();
+	}
+
+	private $_dateFormats = array(
+		'short' => IntlDateFormatter::SHORT,
+		'medium' => IntlDateFormatter::MEDIUM,
+		'long' => IntlDateFormatter::LONG,
+		'full' => IntlDateFormatter::FULL,
+	);
+
+	/**
+	 * Formats the value as a date.
+	 * @param integer|string|DateTime $value the value to be formatted. The following
+	 * types of value are supported:
+	 *
+	 * - an integer representing UNIX timestamp
+	 * - a string that can be parsed into a UNIX timestamp via `strtotime()`
+	 * - a PHP DateTime object
+	 *
+	 * @param string $format the format used to convert the value into a date string.
+	 * If null, [[dateFormat]] will be used. The format string should be the one
+	 * that can be recognized by the PHP `date()` function.
+	 * @return string the formatted result
+	 * @see dateFormat
+	 */
+	public function asDate($value, $format = null)
+	{
+		$value = $this->normalizeDatetimeValue($value);
+		if ($format === null) {
+			$format = $this->dateFormat;
+		}
+		if (isset($this->_dateFormats[$format])) {
+			$formatter = new IntlDateFormatter($this->locale, $this->_dateFormats[$format], IntlDateFormatter::NONE);
+		} else {
+			$formatter = new IntlDateFormatter($this->locale, IntlDateFormatter::NONE, IntlDateFormatter::NONE);
+			$formatter->setPattern($format);
+		}
+		return $formatter->format($value);
+	}
+
+	/**
+	 * Formats the value as a time.
+	 * @param integer|string|DateTime $value the value to be formatted. The following
+	 * types of value are supported:
+	 *
+	 * - an integer representing UNIX timestamp
+	 * - a string that can be parsed into a UNIX timestamp via `strtotime()`
+	 * - a PHP DateTime object
+	 *
+	 * @param string $format the format used to convert the value into a date string.
+	 * If null, [[dateFormat]] will be used. The format string should be the one
+	 * that can be recognized by the PHP `date()` function.
+	 * @return string the formatted result
+	 * @see timeFormat
+	 */
+	public function asTime($value, $format = null)
+	{
+		$value = $this->normalizeDatetimeValue($value);
+		if ($format === null) {
+			$format = $this->timeFormat;
+		}
+		if (isset($this->_dateFormats[$format])) {
+			$formatter = new IntlDateFormatter($this->locale, IntlDateFormatter::NONE, $this->_dateFormats[$format]);
+		} else {
+			$formatter = new IntlDateFormatter($this->locale, IntlDateFormatter::NONE, IntlDateFormatter::NONE);
+			$formatter->setPattern($format);
+		}
+		return $formatter->format($value);
+	}
+
+	/**
+	 * Formats the value as a datetime.
+	 * @param integer|string|DateTime $value the value to be formatted. The following
+	 * types of value are supported:
+	 *
+	 * - an integer representing UNIX timestamp
+	 * - a string that can be parsed into a UNIX timestamp via `strtotime()`
+	 * - a PHP DateTime object
+	 *
+	 * @param string $format the format used to convert the value into a date string.
+	 * If null, [[dateFormat]] will be used. The format string should be the one
+	 * that can be recognized by the PHP `date()` function.
+	 * @return string the formatted result
+	 * @see datetimeFormat
+	 */
+	public function asDatetime($value, $format = null)
+	{
+		$value = $this->normalizeDatetimeValue($value);
+		if ($format === null) {
+			$format = $this->datetimeFormat;
+		}
+		if (isset($this->_dateFormats[$format])) {
+			$formatter = new IntlDateFormatter($this->locale, $this->_dateFormats[$format], $this->_dateFormats[$format]);
+		} else {
+			$formatter = new IntlDateFormatter($this->locale, IntlDateFormatter::NONE, IntlDateFormatter::NONE);
+			$formatter->setPattern($format);
+		}
+		return $formatter->format($value);
+	}
+
+	/**
+	 * Formats the value as a decimal number.
+	 * @param mixed $value the value to be formatted
+	 * @param string $format the format to be used. Please refer to [ICU manual](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details)
+	 * for details on how to specify a format.
+	 * @return string the formatted result.
+	 */
+	public function asDecimal($value, $format = null)
+	{
+		$this->createNumberFormatter(NumberFormatter::DECIMAL, $format)->format($value);
+	}
+
+	/**
+	 * Formats the value as a currency number.
+	 * @param mixed $value the value to be formatted
+	 * @param string $currency the 3-letter ISO 4217 currency code indicating the currency to use.
+	 * @param string $format the format to be used. Please refer to [ICU manual](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details)
+	 * for details on how to specify a format.
+	 * @return string the formatted result.
+	 */
+	public function asCurrency($value, $currency = 'USD', $format = null)
+	{
+		$this->createNumberFormatter(NumberFormatter::CURRENCY, $format)->formatCurrency($value, $currency);
+	}
+
+	/**
+	 * Formats the value as a percent number.
+	 * @param mixed $value the value to be formatted
+	 * @param string $format the format to be used. Please refer to [ICU manual](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details)
+	 * for details on how to specify a format.
+	 * @return string the formatted result.
+	 */
+	public function asPercent($value, $format = null)
+	{
+		$this->createNumberFormatter(NumberFormatter::PERCENT, $format)->format($value);
+	}
+
+	/**
+	 * Formats the value as a scientific number.
+	 * @param mixed $value the value to be formatted
+	 * @param string $format the format to be used. Please refer to [ICU manual](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details)
+	 * for details on how to specify a format.
+	 * @return string the formatted result.
+	 */
+	public function asScientific($value, $format = null)
+	{
+		$this->createNumberFormatter(NumberFormatter::SCIENTIFIC, $format)->format($value);
+	}
+
+	/**
+	 * Creates a number formatter based on the given type and format.
+	 * @param integer $type the type of the number formatter
+	 * @param string $format the format to be used
+	 * @return NumberFormatter the created formatter instance
+	 */
+	protected function createNumberFormatter($type, $format)
+	{
+		$formatter = new NumberFormatter($this->locale, $type);
+		if ($format !== null) {
+			$formatter->setPattern($format);
+		}
+		if (!empty($this->numberFormatOptions)) {
+			foreach ($this->numberFormatOptions as $name => $attribute) {
+				$formatter->setAttribute($name, $attribute);
+			}
+		}
+		return $formatter;
+	}
+}

tests/unit/framework/base/FormatterTest.php

+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+namespace yiiunit\framework\base;
+
+use yii\base\Formatter;
+use yiiunit\TestCase;
+
+/**
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @since 2.0
+ */
+class FormatterTest extends TestCase
+{
+	/**
+	 * @var Formatter
+	 */
+	protected $formatter;
+
+	protected function setUp()
+	{
+		parent::setUp();
+		$this->mockApplication();
+		$this->formatter = new Formatter();
+	}
+
+	protected function tearDown()
+	{
+		parent::tearDown();
+		$this->formatter = null;
+	}
+
+	public function testAsRaw()
+	{
+		$value = '123';
+		$this->assertSame($value, $this->formatter->asRaw($value));
+		$value = 123;
+		$this->assertSame($value, $this->formatter->asRaw($value));
+		$value = '<>';
+		$this->assertSame($value, $this->formatter->asRaw($value));
+	}
+
+	public function testAsText()
+	{
+		$value = '123';
+		$this->assertSame($value, $this->formatter->asText($value));
+		$value = 123;
+		$this->assertSame("$value", $this->formatter->asText($value));
+		$value = '<>';
+		$this->assertSame('&lt;&gt;', $this->formatter->asText($value));
+	}
+
+	public function testAsNtext()
+	{
+		$value = '123';
+		$this->assertSame($value, $this->formatter->asNtext($value));
+		$value = 123;
+		$this->assertSame("$value", $this->formatter->asNtext($value));
+		$value = '<>';
+		$this->assertSame('&lt;&gt;', $this->formatter->asNtext($value));
+		$value = "123\n456";
+		$this->assertSame("123<br />\n456", $this->formatter->asNtext($value));
+	}
+
+	public function testAsParagraphs()
+	{
+		$value = '123';
+		$this->assertSame("<p>$value</p>", $this->formatter->asParagraphs($value));
+		$value = 123;
+		$this->assertSame("<p>$value</p>", $this->formatter->asParagraphs($value));
+		$value = '<>';
+		$this->assertSame('<p>&lt;&gt;</p>', $this->formatter->asParagraphs($value));
+		$value = "123\n456";
+		$this->assertSame("<p>123\n456</p>", $this->formatter->asParagraphs($value));
+		$value = "123\n\n456";
+		$this->assertSame("<p>123</p>\n<p>456</p>", $this->formatter->asParagraphs($value));
+		$value = "123\n\n\n456";
+		$this->assertSame("<p>123</p>\n<p>456</p>", $this->formatter->asParagraphs($value));
+	}
+
+	public function testAsHtml()
+	{
+		// todo
+	}
+
+	public function testAsEmail()
+	{
+		$value = 'test@sample.com';
+		$this->assertSame("<a href=\"mailto:$value\">$value</a>", $this->formatter->asEmail($value));
+	}
+
+	public function testAsImage()
+	{
+		$value = 'http://sample.com/img.jpg';
+		$this->assertSame("<img src=\"$value\" alt=\"\" />", $this->formatter->asImage($value));
+	}
+}