Formatter

Type

Class

Namespace

craft\i18n

Inherits

craft\i18n\Formatter » yii\i18n\Formatter (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

Since

3.0.0

View source (opens new window)

Public Properties

Property	Description
amName	string (opens new window), null (opens new window) – The localized AM name.
baseUnits (opens new window)	array (opens new window) – The base units that are used as multipliers for smallest possible unit from measureUnits (opens new window).
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
booleanFormat (opens new window)	array (opens new window) – The text to be displayed when formatting a boolean value.
calendar (opens new window)	IntlCalendar (opens new window), integer (opens new window), null (opens new window) – The calendar to be used for date formatting.
currencyCode (opens new window)	string (opens new window), null (opens new window) – The 3-letter ISO 4217 currency code indicating the default currency to use for asCurrency() (opens new window).
currencyDecimalSeparator (opens new window)	string (opens new window), null (opens new window) – The character displayed as the decimal point when formatting a currency.
currencySymbols	array (opens new window), null (opens new window) – The locale's currency symbols.
dateFormat (opens new window)	string (opens new window) – The default format string to be used to format a date (opens new window).
dateTimeFormats	array (opens new window) – The locale’s date/time formats.
datetimeFormat (opens new window)	string (opens new window) – The default format string to be used to format a date and time (opens new window).
decimalSeparator (opens new window)	string (opens new window), null (opens new window) – The character displayed as the decimal point when formatting a number.
defaultTimeZone (opens new window)	string (opens new window) – The time zone that is assumed for input values if they do not include a time zone explicitly.
language (opens new window)	string (opens new window), null (opens new window) – The language code (e.g. en-US, en) that is used to translate internal messages.
locale (opens new window)	string (opens new window), null (opens new window) – The locale ID that is used to localize the date and number formatting.
measureUnits (opens new window)	array (opens new window) – Configuration of weight and length measurement units.
monthNames	array (opens new window), null (opens new window) – The localized month names.
nullDisplay (opens new window)	string (opens new window), null (opens new window) – The text to be displayed when formatting a null value.
numberFormatterOptions (opens new window)	array (opens new window) – A list of name value pairs that are passed to the intl [NumberFormatter::setAttribute()](https://www.
numberFormatterSymbols (opens new window)	array (opens new window) – A list of name value pairs that are passed to the intl [NumberFormatter::setSymbol()](https://www.
numberFormatterTextOptions (opens new window)	array (opens new window) – A list of name value pairs that are passed to the intl [NumberFormatter::setTextAttribute()](https://www.
pmName	string (opens new window), null (opens new window) – The localized PM name.
sizeFormatBase (opens new window)	integer (opens new window) – The base at which a kilobyte is calculated (1000 or 1024 bytes per kilobyte), used by asSize() (opens new window) and asShortSize() (opens new window).
standAloneMonthNames	array (opens new window), null (opens new window) – The localized "stand alone" month names.
standAloneWeekDayNames	array (opens new window), null (opens new window) – The localized "stand alone" day of the week names.
systemOfUnits (opens new window)	string (opens new window) – Default system of measure units.
thousandSeparator (opens new window)	string (opens new window), null (opens new window) – The character displayed as the thousands separator (also called grouping separator) character when formatting a number.
timeFormat (opens new window)	string (opens new window) – The default format string to be used to format a time (opens new window).
timeZone (opens new window)	string (opens new window), null (opens new window) – The time zone to use for formatting time and date values.
weekDayNames	array (opens new window), null (opens new window) – The localized day of the week names.

amName

Type

string (opens new window), null (opens new window)

Default value

null

The localized AM name.

View source (opens new window)

currencySymbols

Type

array (opens new window), null (opens new window)

Default value

null

The locale's currency symbols.

View source (opens new window)

dateTimeFormats

Type

array (opens new window)

Default value

null

The locale’s date/time formats.

View source (opens new window)

monthNames

Type

array (opens new window), null (opens new window)

Default value

null

The localized month names.

View source (opens new window)

pmName

Type

string (opens new window), null (opens new window)

Default value

null

The localized PM name.

View source (opens new window)

standAloneMonthNames

Type

array (opens new window), null (opens new window)

Default value

null

The localized "stand alone" month names.

View source (opens new window)

standAloneWeekDayNames

Type

array (opens new window), null (opens new window)

Default value

null

The localized "stand alone" day of the week names.

View source (opens new window)

weekDayNames

Type

array (opens new window), null (opens new window)

Default value

null

The localized day of the week names.

View source (opens new window)

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
asBoolean() (opens new window)	Formats the value as a boolean.
asCurrency()	Formats the value as a currency number.
asDate()	Formats the value as a date.
asDatetime()	Formats the value as a datetime.
asDecimal() (opens new window)	Formats the value as a decimal number.
asDuration() (opens new window)	Represents the value as duration in human readable format.
asEmail() (opens new window)	Formats the value as a mailto link.
asHtml() (opens new window)	Formats the value as HTML text.
asImage() (opens new window)	Formats the value as an image tag.
asInteger() (opens new window)	Formats the value as an integer number by removing any decimal digits without rounding.
asLength() (opens new window)	Formats the value as a length in human readable form for example 12 meters.
asNtext() (opens new window)	Formats the value as an HTML-encoded plain text with newlines converted into breaks.
asOrdinal() (opens new window)	Formats the value as a ordinal value of a number.
asParagraphs() (opens new window)	Formats the value as HTML-encoded text paragraphs.
asPercent()	Formats the value as a percent number with "%" sign.
asRaw() (opens new window)	Formats the value as is without any formatting.
asRelativeTime() (opens new window)	Formats the value as the time interval between a date and now in human readable form.
asScientific() (opens new window)	Formats the value as a scientific number.
asShortLength() (opens new window)	Formats the value as a length in human readable form for example 12 m.
asShortSize()	Formats the value in bytes as a size in human readable form for example 12 kB.
asShortWeight() (opens new window)	Formats the value as a weight in human readable form for example 12 kg.
asSize() (opens new window)	Formats the value in bytes as a size in human readable form, for example 12 kilobytes.
asSpellout() (opens new window)	Formats the value as a number spellout.
asText()	Formats the value as an HTML-encoded plain text.
asTime()	Formats the value as a time.
asTimestamp()	Formats the value as a human-readable timestamp.
asUrl() (opens new window)	Formats the value as a hyperlink.
asWeight() (opens new window)	Formats the value as a weight in human readable form for example 12 kilograms.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	Returns the fully qualified name of this class.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
format() (opens new window)	Formats the value based on the given format type.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes the object.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	Attaches an event handler to an event.
trigger() (opens new window)	Triggers an event.
willBeMisrepresented()	Returns whether the given number will be misrepresented when formatted.

asCurrency()

Formats the value as a currency number.

View source (opens new window)

Arguments

• $value (mixed) – The value to be formatted.
• $currency (string (opens new window), null (opens new window)) – The 3-letter ISO 4217 currency code indicating the currency to use. If null, currencyCode (opens new window) will be used.
• $options (array (opens new window)) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterOptions (opens new window).
• $textOptions (array (opens new window)) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterTextOptions (opens new window).
• $stripZeros (boolean (opens new window)) – Whether the formatted currency should remove the fraction digits if $value has no minor value (e.g. cents).

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
  if the input value is not numeric.
• yii\base\InvalidConfigException (opens new window)
  if no currency is given and currencyCode (opens new window) is not defined.

asDate()

Formats the value as a date.

View source (opens new window)

Arguments

• $value (integer (opens new window), string (opens new window), DateTime (opens new window)) – The value to be formatted. The following types of value are supported:

• an integer representing a UNIX timestamp. A UNIX timestamp is always in UTC by its definition.

• a string that can be parsed to create a DateTime object (opens new window). The timestamp is assumed to be in defaultTimeZone (opens new window) unless a time zone is explicitly given.

• a PHP DateTime (opens new window) object. You may set the time zone for the DateTime object to specify the source time zone.

The formatter will convert date values according to timeZone (opens new window) before formatting it. If no timezone conversion should be performed, you need to set defaultTimeZone (opens new window) and timeZone (opens new window) to the same value. Also no conversion will be performed on values that have no time information, e.g. "2017-06-05".

• $format (string (opens new window), null (opens new window)) – The format used to convert the value into a date string. If null, dateFormat (opens new window) will be used.

This can be "short", "medium", "long", or "full", which represents a preset format of different lengths. It can also be a custom format as specified in the ICU manual (opens new window).

Alternatively this can be a string prefixed with php: representing a format that can be recognized by the PHP date() (opens new window)-function.

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
• yii\base\InvalidConfigException (opens new window)

asDatetime()

Formats the value as a datetime.

View source (opens new window)

Arguments

• $value (integer (opens new window), string (opens new window), DateTime (opens new window)) – The value to be formatted. The following types of value are supported:

• an integer representing a UNIX timestamp. A UNIX timestamp is always in UTC by its definition.

• a string that can be parsed to create a DateTime object (opens new window). The timestamp is assumed to be in defaultTimeZone (opens new window) unless a time zone is explicitly given.

• a PHP DateTime (opens new window) object. You may set the time zone for the DateTime object to specify the source time zone.

The formatter will convert date values according to timeZone (opens new window) before formatting it. If no timezone conversion should be performed, you need to set defaultTimeZone (opens new window) and timeZone (opens new window) to the same value.

• $format (string (opens new window), null (opens new window)) – The format used to convert the value into a date string. If null, datetimeFormat (opens new window) will be used.

This can be "short", "medium", "long", or "full", which represents a preset format of different lengths. It can also be a custom format as specified in the ICU manual (opens new window).

Alternatively this can be a string prefixed with php: representing a format that can be recognized by the PHP date() (opens new window)-function.

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
• yii\base\InvalidConfigException (opens new window)

asPercent()

Formats the value as a percent number with "%" sign.

Since 2.0.16 numbers that are mispresented after normalization are formatted as strings using fallback function without PHP intl extension (opens new window) support. For very big numbers it's recommended to pass them as strings and not use scientific notation otherwise the output might be wrong.

View source (opens new window)

Arguments

• $value (mixed) – The value to be formatted. It must be a factor e.g. 0.75 will result in 75%.
• $decimals (integer (opens new window), null (opens new window)) – The number of digits after the decimal point. If not given, the number of digits depends in the input value and is determined based on NumberFormatter::MIN_FRACTION_DIGITS and NumberFormatter::MAX_FRACTION_DIGITS, which can be configured using numberFormatterOptions (opens new window). If the PHP intl extension is not available, the default value is 0. If you want consistent behavior between environments where intl is available and not, you should explicitly specify a value here.
• $options (array (opens new window)) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterOptions (opens new window).
• $textOptions (array (opens new window)) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterTextOptions (opens new window).

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
  if the input value is not numeric or the formatting failed.

asShortSize()

Since

3.4.0

Formats the value in bytes as a size in human readable form for example 12 kB.

This is the short form of asSize() (opens new window).

If sizeFormatBase (opens new window) is 1024, binary prefixes (opens new window) (e.g. kibibyte/KiB, mebibyte/MiB, ...) are used in the formatting result.

View source (opens new window)

Arguments

• $value (string (opens new window), integer (opens new window), float (opens new window), null (opens new window)) – Value in bytes to be formatted.
• $decimals (integer (opens new window), null (opens new window)) – The number of digits after the decimal point.
• $options (array (opens new window)) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterOptions (opens new window).
• $textOptions (array (opens new window)) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterTextOptions (opens new window).

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
  if the input value is not numeric or the formatting failed.

asText()

Formats the value as an HTML-encoded plain text.

View source (opens new window)

Arguments

• $value (string (opens new window), DateTime (opens new window), null (opens new window)) – The value to be formatted.

Returns

string (opens new window) – The formatted result.

asTime()

Formats the value as a time.

View source (opens new window)

Arguments

• $value (integer (opens new window), string (opens new window), DateTime (opens new window)) – The value to be formatted. The following types of value are supported:

• an integer representing a UNIX timestamp. A UNIX timestamp is always in UTC by its definition.

• a string that can be parsed to create a DateTime object (opens new window). The timestamp is assumed to be in defaultTimeZone (opens new window) unless a time zone is explicitly given.

• a PHP DateTime (opens new window) object. You may set the time zone for the DateTime object to specify the source time zone.

The formatter will convert date values according to timeZone (opens new window) before formatting it. If no timezone conversion should be performed, you need to set defaultTimeZone (opens new window) and timeZone (opens new window) to the same value.

• $format (string (opens new window), null (opens new window)) – The format used to convert the value into a date string. If null, timeFormat (opens new window) will be used.

This can be "short", "medium", "long", or "full", which represents a preset format of different lengths. It can also be a custom format as specified in the ICU manual (opens new window).

Alternatively this can be a string prefixed with php: representing a format that can be recognized by the PHP date() (opens new window)-function.

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
• yii\base\InvalidConfigException (opens new window)

asTimestamp()

Formats the value as a human-readable timestamp.

• If $value is from today, "Today" or the formatted time will be returned, depending on whether $value contains time information
• If $value is from yesterday, "Yesterday" will be returned
• If $value is within the past 7 days, the weekday will be returned

See also datetimeFormat (opens new window) View source (opens new window)

Arguments

• $value (integer (opens new window), string (opens new window), DateTime (opens new window)) – The value to be formatted. The following types of value are supported:
• an int representing a UNIX timestamp
• a string that can be parsed to create a DateTime object (opens new window). The timestamp is assumed to be in defaultTimeZone (opens new window) unless a time zone is explicitly given.
• a PHP DateTime (opens new window) object
• $format (string (opens new window), null (opens new window)) – The format used to convert the value into a date string. If null, dateFormat (opens new window) will be used. This can be "short", "medium", "long", or "full", which represents a preset format of different lengths. It can also be a custom format as specified in the ICU manual (opens new window). Alternatively this can be a string prefixed with php: representing a format that can be recognized by the PHP date() (opens new window)-function.
• $withPreposition (boolean (opens new window)) – Whether a preposition should be included in the returned string (e.g. “at 12:00 PM” or “on Wednesday”).

Returns

string (opens new window) – The formatted result.

Throws

• yii\base\InvalidArgumentException (opens new window)
  if the input value can not be evaluated as a date value.
• yii\base\InvalidConfigException (opens new window)
  if the date format is invalid.

willBeMisrepresented()

Since

3.7.24

Returns whether the given number will be misrepresented when formatted.

See also isNormalizedValueMispresented() (opens new window) View source (opens new window)

Arguments

• $value (mixed) – The value to be formatted.

Returns

boolean (opens new window)

Protected Methods

Method	Description
asCurrencyStringFallback() (opens new window)	Fallback for formatting value as a currency number.
asDecimalStringFallback() (opens new window)	Fallback for formatting value as a decimal number.
asIntegerStringFallback() (opens new window)	Fallback for formatting value as an integer number by removing any decimal digits without rounding.
asPercentStringFallback() (opens new window)	Fallback for formatting value as a percent number with "%" sign.
createNumberFormatter() (opens new window)	Creates a number formatter based on the given type and format.
formatNumber() (opens new window)	Given the value in bytes formats number part of the human readable form.
isNormalizedValueMispresented() (opens new window)	Checks if string representations of given value and its normalized version are different.
normalizeDatetimeValue() (opens new window)	Normalizes the given datetime value as a DateTime object that can be taken by various date/time formatting methods.
normalizeNumericStringValue() (opens new window)	Normalizes a numeric string value.
normalizeNumericValue() (opens new window)	Normalizes a numeric input value.

Constants

Constant	Description
FORMAT_WIDTH_LONG
FORMAT_WIDTH_SHORT
UNIT_LENGTH
UNIT_SYSTEM_IMPERIAL
UNIT_SYSTEM_METRIC
UNIT_WEIGHT