Formatter.php 10.7 KB
Newer Older
Qiang Xue committed
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
<?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';
39 40 41 42
	/**
	 * @var string the text to be displayed when formatting a null. Defaults to '(not set)'.
	 */
	public $nullDisplay;
Qiang Xue committed
43 44
	/**
	 * @var array the text to be displayed when formatting a boolean value. The first element corresponds
45
	 * to the text display for false, the second element for true. Defaults to `array('No', 'Yes')`.
Qiang Xue committed
46 47
	 */
	public $booleanFormat;
48 49
	/**
	 * @var string the character displayed as the decimal point when formatting a number.
50
	 * If not set, "." will be used.
51
	 */
52
	public $decimalSeparator;
53 54
	/**
	 * @var string the character displayed as the thousands separator character when formatting a number.
55
	 * If not set, "," will be used.
56
	 */
57
	public $thousandSeparator;
Qiang Xue committed
58 59 60 61 62 63 64 65 66 67


	/**
	 * Initializes the component.
	 */
	public function init()
	{
		if (empty($this->booleanFormat)) {
			$this->booleanFormat = array(Yii::t('yii', 'No'), Yii::t('yii', 'Yes'));
		}
68 69 70
		if ($this->nullDisplay === null) {
			$this->nullDisplay = Yii::t('yii', '(not set)');
		}
Qiang Xue committed
71 72
	}

Qiang Xue committed
73
	/**
Qiang Xue committed
74
	 * Formats the value based on the given type.
Qiang Xue committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
	 * This method will call one of the "as" methods available in this class to do the formatting.
	 * For type "xyz", the method "asXyz" will be used. For example, if the type is "html",
	 * then [[asHtml()]] will be used. Type names are case insensitive.
	 * @param mixed $value the value to be formatted
	 * @param string $type the type of the value, e.g., "html", "text".
	 * @return string the formatting result
	 * @throws InvalidParamException if the type is not supported by this class.
	 */
	public function format($value, $type)
	{
		$method = 'as' . $type;
		if (method_exists($this, $method)) {
			return $this->$method($value);
		} else {
			throw new InvalidParamException("Unknown type: $type");
		}
	}

Qiang Xue committed
93 94 95 96 97 98 99 100
	/**
	 * 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)
	{
101 102 103
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
104 105 106 107 108 109 110 111 112 113
		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)
	{
114 115 116
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
117 118 119 120 121 122 123 124 125 126
		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)
	{
127 128 129
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
130 131 132 133 134 135 136 137 138 139 140 141
		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)
	{
142 143 144
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
		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)
	{
160 161 162
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
163 164 165 166 167 168 169 170 171 172
		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)
	{
173 174 175
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
176 177 178 179 180 181 182 183 184 185
		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)
	{
186 187 188
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
189 190 191 192 193 194 195 196 197 198
		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)
	{
199 200 201
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
		$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)
	{
217 218 219
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
220 221 222 223 224 225 226 227
		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:
	 *
228
	 * - an integer representing a UNIX timestamp
Qiang Xue committed
229 230 231 232
	 * - 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.
233
	 * If null, [[dateFormat]] will be used. The format string should be one
Qiang Xue committed
234 235 236 237 238 239
	 * that can be recognized by the PHP `date()` function.
	 * @return string the formatted result
	 * @see dateFormat
	 */
	public function asDate($value, $format = null)
	{
240 241 242
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
243 244 245 246 247 248 249 250 251
		$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:
	 *
252
	 * - an integer representing a UNIX timestamp
Qiang Xue committed
253 254 255 256
	 * - 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.
257
	 * If null, [[timeFormat]] will be used. The format string should be one
Qiang Xue committed
258 259 260 261 262 263
	 * that can be recognized by the PHP `date()` function.
	 * @return string the formatted result
	 * @see timeFormat
	 */
	public function asTime($value, $format = null)
	{
264 265 266
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
267 268 269 270 271 272 273 274 275
		$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:
	 *
276
	 * - an integer representing a UNIX timestamp
Qiang Xue committed
277 278 279 280
	 * - 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.
281
	 * If null, [[datetimeFormat]] will be used. The format string should be one
Qiang Xue committed
282 283 284 285 286 287
	 * that can be recognized by the PHP `date()` function.
	 * @return string the formatted result
	 * @see datetimeFormat
	 */
	public function asDatetime($value, $format = null)
	{
288 289 290
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
		$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)
	{
322 323 324
		if ($value === null) {
			return $this->nullDisplay;
		}
Qiang Xue committed
325 326 327 328 329 330 331 332 333 334
		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.
335
	 * Property [[decimalSeparator]] will be used to represent the decimal point.
Qiang Xue committed
336 337 338
	 * @param mixed $value the value to be formatted
	 * @param integer $decimals the number of digits after the decimal point
	 * @return string the formatting result.
339
	 * @see decimalSeparator
Qiang Xue committed
340 341 342
	 */
	public function asDouble($value, $decimals = 2)
	{
343 344 345
		if ($value === null) {
			return $this->nullDisplay;
		}
346 347 348 349 350
		if ($this->decimalSeparator === null) {
			return sprintf("%.{$decimals}f", $value);
		} else {
			return str_replace('.', $this->decimalSeparator, sprintf("%.{$decimals}f", $value));
		}
Qiang Xue committed
351 352 353
	}

	/**
Qiang Xue committed
354 355
	 * Formats the value as a number with decimal and thousand separators.
	 * This method calls the PHP number_format() function to do the formatting.
Qiang Xue committed
356 357 358
	 * @param mixed $value the value to be formatted
	 * @param integer $decimals the number of digits after the decimal point
	 * @return string the formatted result
359 360
	 * @see decimalSeparator
	 * @see thousandSeparator
Qiang Xue committed
361
	 */
362
	public function asNumber($value, $decimals = 0)
Qiang Xue committed
363
	{
364 365 366
		if ($value === null) {
			return $this->nullDisplay;
		}
367 368 369
		$ds = isset($this->decimalSeparator) ? $this->decimalSeparator: '.';
		$ts = isset($this->thousandSeparator) ? $this->thousandSeparator: ',';
		return number_format($value, $decimals, $ds, $ts);
Qiang Xue committed
370 371
	}
}