Formatter

Type

Class

Namespace

craft\i18n

Inherits

craft\i18n\Formatter » yii\i18n\Formatter » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

3.0.0

View source

Public Properties

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

amName

Type

string, null

Default value

null

The localized AM name.

View source

currencySymbols

Type

array, null

Default value

null

The locale's currency symbols.

View source

dateTimeFormats

Type

array

Default value

null

The locale’s date/time formats.

View source

monthNames

Type

array, null

Default value

null

The localized month names.

View source

pmName

Type

string, null

Default value

null

The localized PM name.

View source

standAloneMonthNames

Type

array, null

Default value

null

The localized "stand alone" month names.

View source

standAloneWeekDayNames

Type

array, null

Default value

null

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

View source

weekDayNames

Type

array, null

Default value

null

The localized day of the week names.

View source

Public Methods

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

asCurrency()

Formats the value as a currency number.

View source

Arguments

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

Returns

string – The formatted result.

Throws

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

asDate()

Formats the value as a date.

View source

Arguments

• $value (integer, string, DateTime) – 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. The timestamp is assumed to be in defaultTimeZone unless a time zone is explicitly given.

• a PHP DateTime 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 before formatting it. If no timezone conversion should be performed, you need to set defaultTimeZone and timeZone to the same value. Also no conversion will be performed on values that have no time information, e.g. "2017-06-05".

• $format (string, null) – The format used to convert the value into a date string. If null, dateFormat 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.

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

Returns

string – The formatted result.

Throws

• yii\base\InvalidArgumentException
• yii\base\InvalidConfigException

asDatetime()

Formats the value as a datetime.

View source

Arguments

• $value (integer, string, DateTime) – 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. The timestamp is assumed to be in defaultTimeZone unless a time zone is explicitly given.

• a PHP DateTime 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 before formatting it. If no timezone conversion should be performed, you need to set defaultTimeZone and timeZone to the same value.

• $format (string, null) – The format used to convert the value into a date string. If null, datetimeFormat 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.

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

Returns

string – The formatted result.

Throws

• yii\base\InvalidArgumentException
• yii\base\InvalidConfigException

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 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

Arguments

• $value (mixed) – The value to be formatted. It must be a factor e.g. 0.75 will result in 75%.
• $decimals (integer, null) – 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. 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) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterOptions.
• $textOptions (array) – Optional configuration for the number formatter. This parameter will be merged with numberFormatterTextOptions.

Returns

string – The formatted result.

Throws

• yii\base\InvalidArgumentException
  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().

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

View source

Arguments

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

Returns

string – The formatted result.

Throws

• yii\base\InvalidArgumentException
  if the input value is not numeric or the formatting failed.

asText()

Formats the value as an HTML-encoded plain text.

View source

Arguments

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

Returns

string – The formatted result.

asTime()

Formats the value as a time.

View source

Arguments

• $value (integer, string, DateTime) – 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. The timestamp is assumed to be in defaultTimeZone unless a time zone is explicitly given.

• a PHP DateTime 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 before formatting it. If no timezone conversion should be performed, you need to set defaultTimeZone and timeZone to the same value.

• $format (string, null) – The format used to convert the value into a date string. If null, timeFormat 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.

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

Returns

string – The formatted result.

Throws

• yii\base\InvalidArgumentException
• yii\base\InvalidConfigException

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 datetimeFormatView source

Arguments

• $value (integer, string, DateTime) – 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. The timestamp is assumed to be in defaultTimeZone unless a time zone is explicitly given.
• a PHP DateTime object
• $format (string, null) – The format used to convert the value into a date string. If null, dateFormat 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. Alternatively this can be a string prefixed with php: representing a format that can be recognized by the PHP date()-function.
• $withPreposition (boolean) – Whether a preposition should be included in the returned string (e.g. “at 12:00 PM” or “on Wednesday”).

Returns

string – The formatted result.

Throws

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

willBeMisrepresented()

Since

3.7.24

Returns whether the given number will be misrepresented when formatted.

See also isNormalizedValueMispresented()View source

Arguments

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

Returns

boolean

Protected Methods

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

Constants

Constant	Description
FORMAT_WIDTH_LONG
FORMAT_WIDTH_SHORT
UNIT_LENGTH
UNIT_SYSTEM_IMPERIAL
UNIT_SYSTEM_METRIC
UNIT_WEIGHT