Important

You are browsing documentation for version 5.0 of OroCommerce, supported until January 2025. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Number Formatting

PHP Number Formatter

Class: Oro\Bundle\LocaleBundle\Formatter\NumberFormatter

Service id: oro_locale.formatter.number

This class formats different styles of numbers in localized format and proxies intl extension class NumberFormatter.

Constants

Methods of Number Formatter can receive values of original intl NumberFormatter constants.

Each constant can be passed to an appropriate method of Number Formatter as a string name, for example, case insensitive: “DECIMAL_SEPARATOR_SYMBOL”, “currency_code”.

Constants can be divided into the following logical groups:

Format Style Constants

\NumberFormatter::PATTERN_DECIMAL
\NumberFormatter::DECIMAL
\NumberFormatter::CURRENCY
\NumberFormatter::PERCENT
\NumberFormatter::SCIENTIFIC
\NumberFormatter::SPELLOUT
\NumberFormatter::ORDINAL
\NumberFormatter::DURATION
\NumberFormatter::PATTERN_RULEBASED
\NumberFormatter::IGNORE
\NumberFormatter::DEFAULT_STYLE

Numeric Attribute Constants

\NumberFormatter::PARSE_INT_ONLY
\NumberFormatter::GROUPING_USED
\NumberFormatter::DECIMAL_ALWAYS_SHOWN
\NumberFormatter::MAX_INTEGER_DIGITS
\NumberFormatter::MIN_INTEGER_DIGITS
\NumberFormatter::INTEGER_DIGITS
\NumberFormatter::MAX_FRACTION_DIGITS
\NumberFormatter::MIN_FRACTION_DIGITS
\NumberFormatter::FRACTION_DIGITS
\NumberFormatter::MULTIPLIER
\NumberFormatter::GROUPING_SIZE
\NumberFormatter::ROUNDING_MODE
\NumberFormatter::ROUNDING_INCREMENT
\NumberFormatter::FORMAT_WIDTH
\NumberFormatter::PADDING_POSITION
\NumberFormatter::SECONDARY_GROUPING_SIZE
\NumberFormatter::SIGNIFICANT_DIGITS_USED
\NumberFormatter::MIN_SIGNIFICANT_DIGITS
\NumberFormatter::MAX_SIGNIFICANT_DIGITS
\NumberFormatter::LENIENT_PARSE

Text Attribute Constants

NumberFormatter::POSITIVE_PREFIX NumberFormatter::POSITIVE_SUFFIX NumberFormatter::NEGATIVE_PREFIX NumberFormatter::NEGATIVE_SUFFIX NumberFormatter::PADDING_CHARACTER NumberFormatter::CURRENCY_CODE NumberFormatter::DEFAULT_RULESET NumberFormatter::PUBLIC_RULESETS

Format Symbol Constants

\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL
\NumberFormatter::GROUPING_SEPARATOR_SYMBOL
\NumberFormatter::PATTERN_SEPARATOR_SYMBOL
\NumberFormatter::PERCENT_SYMBOL
\NumberFormatter::ZERO_DIGIT_SYMBOL
\NumberFormatter::DIGIT_SYMBOL
\NumberFormatter::MINUS_SIGN_SYMBOL
\NumberFormatter::PLUS_SIGN_SYMBOL
\NumberFormatter::CURRENCY_SYMBOL
\NumberFormatter::INTL_CURRENCY_SYMBOL
\NumberFormatter::MONETARY_SEPARATOR_SYMBOL
\NumberFormatter::EXPONENTIAL_SYMBOL
\NumberFormatter::PERMILL_SYMBOL
\NumberFormatter::PAD_ESCAPE_SYMBOL
\NumberFormatter::INFINITY_SYMBOL
\NumberFormatter::NAN_SYMBOL
\NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL
\NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL

Methods and Usage Examples

format

string *public* *format*(mixed *value*, string|int *style*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

This method can be used to format any style of numbers that are passed directly as the second argument. A list of custom attributes, text attributes, symbols and locale can be passed as well.

// Simple usage default locale and related number format will be used
echo $numberFormatter->format(1234.56789, \NumberFormatter::DECIMAL);
// outputs: "1,234.568" if default locale is en_US

// Use custom attributes and custom locale
echo $numberFormatter->format(
    -100000.123,
    \NumberFormatter::DECIMAL,
    'attributes' => [\NumberFormatter::GROUPING_SIZE => 4],
    'textAttributes' => [\NumberFormatter::NEGATIVE_PREFIX => 'MINUS '],
    'symbols' => [
        \NumberFormatter::DECIMAL_SEPARATOR_SYMBOL => ',',
        \NumberFormatter::GROUPING_SEPARATOR_SYMBOL => '.',
    ],
);
// outputs: "MINUS 10.0000,123"

formatCurrency

string *public* *formatCurrency*(mixed *value*, string *currency*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

Formats currency number. Currency code should be specified, otherwise default currency string *public* *formatCurrency*(mixed *value*, string *currency*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]]) is used.

// Using default locale and currency
echo $numberFormatter->formatCurrency(1234.56789);
// outputs: "$1,234.57" if default locale is en_US and currency is 'USD'

// Specify custom currency and locale
echo $numberFormatter->formatCurrency(1234.56789, 'EUR', [], [], [], 'ru_RU');
// outputs: "1 234,57 €"

formatDecimal

string *public* *formatDecimal*(mixed *value*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

Formats decimal number.

// Using default locale and format
echo $numberFormatter->formatDecimal(1234.56789);
// outputs: "1,234.568" if default locale is en_US and currency is 'USD'

// Specify custom locale and attributes
echo $numberFormatter->formatDecimal(
    1234.56789,
    'attributes' => ['fraction_digits' => 10],
    'textAttributes' => ['positive_prefix' => '+',],
    'symbols' => [\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL => ',', \NumberFormatter::GROUPING_SEPARATOR_SYMBOL => ' '],
    'en_US'
);
// outputs: "+12 345,6789000000"

formatPercent

string *public* *formatPercent*(mixed *value*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

Formats percent number.

echo $numberFormatter->formatPercent(1);
// outputs: "100%"

echo $numberFormatter->formatPercent(.567, [], [], [], 'en_US');
// outputs: "56,7%"

formatSpellout

string *public* *formatSpellout*(mixed *value*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

Formats spellout number. If locale is not specified, the default one will be used.

echo $numberFormatter->formatSpellout(1);
// outputs: "one"

echo $numberFormatter->formatSpellout(21, [], [], [], 'en_US');
// outputs: "twenty-one"

formatDuration

string *public* *formatDuration*(mixed *value*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

Formats duration number. If locale is not specified, the default one is used.

echo $numberFormatter->formatDuration(3661);
// outputs: "1:01:01"

echo $numberFormatter->formatDuration(
    3661,
    [],
    [\NumberFormatter::DEFAULT_RULESET => "%with-words"],
    [],
    'en_US'
);
// outputs: "1 hour, 1 minute, 1 second"

formatOrdinal

string *public* *formatOrdinal*(mixed *value*[, array *attributes*[, array *textAttributes*[, array *symbols*[, string *locale*]]]])

Formats ordinal number. If locale is not specified, the default one is used.

echo $numberFormatter->formatOrdinal(1);
// outputs: "1st"

echo $numberFormatter->formatOrdinal(3, [], [], [], 'en_US');
// outputs: "3rd"

getAttribute

int *public* *getAttribute*(string|int *attribute*[, string|int *style*[, string *locale*]])

Gets numeric attribute of intl NumberFormatter related to passed locale. If locale is not passed, the default one is used.

echo $numberFormatter->getAttribute('parse_int_only', 'decimal', 'en_US');
// outputs: 0

echo $numberFormatter->getAttribute(\NumberFormatter::MAX_INTEGER_DIGITS, \NumberFormatter::DECIMAL, 'en_US');
// outputs: 309

getTextAttribute

string *public* *getTextAttribute*(string|int *textAttribute*[, string|int *style*[, string *locale*]])

Gets text attribute of intl NumberFormatter related to passed locale. If locale is not passed, the default one is used.

echo $numberFormatter->getTextAttribute('negative_prefix', 'decimal', 'en_US');
// outputs: "-"

echo $numberFormatter->getTextAttribute(\NumberFormatter::\NEGATIVE_PREFIX, \NumberFormatter::CURRENCY, 'en_US');
// outputs: "($"

getSymbol

string *public* *getSymbol*(string|int *symbol*[, string|int *style*[, string *locale*]])

Gets symbol of intl NumberFormatter related to passed locale. If locale is not passed, default one will be used.

echo $numberFormatter->getSymbol('DECIMAL_SEPARATOR_SYMBOL', 'DECIMAL', 'en_US');
// outputs: "."

echo $numberFormatter->getSymbol(\NumberFormatter::GROUPING_SEPARATOR_SYMBOL, \NumberFormatter::DECIMAL, 'en_US');
// outputs: ","

Twig

Filters

Each filter can optionally receive attributes, textAttributes and symbols options. All possible options relates to the names of constants of NumberFormatter:

The following filters are available in Twig templates:

oro_format_number

This filter formats a number to the localized format according to the passed number style and optional custom options:

Simple usage of this filter requires a style of number. The following values can be used: decimal, currency, percent, scientific, spellout, ordinal, duration.

This example outputs a string in localized format like this: 10,000.000

{{ 10000|oro_format_number('decimal') }}

This example outputs MINUS 10.0000,123 and shows what options could be passed to customize format.

{{ -100000.123|oro_format_number('decimal', {
    attributes: {grouping_size: 4},
    textAttributes: {negative_prefix: 'MINUS'},
    symbols: {decimal_separator_symbol: ',', grouping_separator_symbol: '.'},
    locale: 'en_US'
}) }}

oro_format_currency

This filter formats currency number according to localized format.

Next example is a simple use case. If currency is not specified, the default one is used. This line outputs a string like this $10,000.00 depending on locale settings.

{{ 100000|oro_format_currency }}

You can override formatting options. The following example demonstrates how custom options can be passed using this filter.

This line outputs a string: (1 2345.78 €)

{{ 12345.6789|oro_format_currency({
    currency: 'EUR',
    locale: 'ru_RU',
    attributes: {grouping_size: 4},
    textAttributes: {negative_prefix: '(', negative_suffix: ')'},
    symbols: {decimal_separator_symbol: '.'},
}) }}

oro_format_decimal

This filter formats decimal number according localized format.

This example outputs a string: 1,234.568

{{ 1234.56789|oro_format_decimal }}

You can override formatting options. This snippet shows an example of using custom formatting options. It outputs the following string: +12 345,6789000000

{{ 1234.56789|oro_format_decimal({
    attributes: { fraction_digits: 10 },
    textAttributes: { positive_prefix: '+' },
    symbols: { decimal_separator: ',', grouping_separator: ' ' },
    locale: 'en_US'
}) }}

oro_format_percent

This filter formats percent number according localized format.

This example outputs a string: 100%

{{ 1|oro_format_percent }}

You can override formatting options. This snippet shows an example of using custom formatting options. It outputs a string: +56,7 %

{{ .5671|oro_format_percent({
    attributes: { fraction_digits: 1 },
    textAttributes: { positive_prefix: '+' },
    symbols: { decimal_separator: ',' },
    locale: 'ru_RU'
}) }}

oro_format_spellout

This filter formats a number in spellout style.

This example outputs a string: “one”

{{ 1|oro_format_spellout }}

This example demonstrates using custom locale in options. Other possible options are: attributes, textAttributes, symbols like in all other Twig number formatters filters in this bundle.

This line outputs a string: twelve

{{ 1|oro_format_spellout({ locale: 'en_US' }) }}

oro_format_duration

This filter formats a number in duration style.

Example of simple usage, this line outputs a string: 1:01:01

{{ 3661|oro_format_duration }}

Next example demonstrates how custom options could be passed. Other possible options are: attributes and symbols like in all other Twig number formatters filters in this bundle.

This line outputs a string: 1 hour, 1 minute, 1 second

{{ 3661|oro_format_duration({
    locale: 'en_US',
    textAttributes: { default_ruleset: '%with-words' }
}) }}

oro_format_ordinal

This filter formats a number in ordinal style.

Example of simple usage, this line outputs a string: 3rd

{{ 3|oro_format_ordinal }}

Next example demonstrates how custom options could be passed. Other possible options are: attributes, textAttributes and symbols like in all other Twig number formatters filters in this bundle.

This line outputs a string: 4th

{{ 4|oro_format_ordinal({
    locale: 'en_US'
}) }}

Functions

The following functions are available in Twig templates:

oro_locale_number_attribute

Gets text attribute of intl NumberFormatter related to passed locale. If locale is not passed, the default one is used.

See available values for arguments are:

• Format style constants

• Numeric attribute constants

This example uses the default locale and outputs the value of \NumberFormatter::PARSE_INT_ONLY for the given number style and locale.

{{ oro_locale_number_attribute('parse_int_only', 'decimal') }}

Custom locale can be passed in the third argument:

{{ oro_locale_number_attribute('max_integer_digits', 'decimal', 'en_US');

oro_locale_number_text_attribute

Gets text attribute of intl NumberFormatter related to passed locale. If locale is not passed, the default one is used.

Available values for arguments are:

• Format style constants

• Text attribute constants

This example uses the default locale and outputs the value of \NumberFormatter::NEGATIVE_PREFIX for the given number style and locale.

{{ oro_locale_number_text_attribute('negative_prefix', 'decimal') }}

Custom locale can be passed in the third argument:

{{ oro_locale_number_text_attribute('negative_prefix', 'decimal', 'ru_RU') }}

oro_locale_number_symbol

Gets symbol of intl NumberFormatter related to the passed locale. If locale is not passed, the default one is used.

Available values for arguments are:

• Format style constants

• Format symbol constants

This example uses the default locale and outputs the value of \NumberFormatter::DECIMAL_SEPARATOR_SYMBOL for the given number style and locale.

{{ oro_locale_number_symbol('decimal_separator_symbol', 'decimal');

Custom locale can be passed in the third argument:

{{ oro_locale_number_symbol('decimal_separator_symbol', 'decimal', 'ru_RU') }}

JS

On JS side number formatter is available via module orolocale/js/formatter/number.

Import it in your code like this:

import numberFormatter from 'orolocale/js/formatter/number';

This module provides the followig functions for different cases:

Functions

formatDecimal

Formats number to decimal localized format.

Example of usage:

 import numberFormatter from 'orolocale/js/formatter/number';

 // 10,000.000 depending on locale settings
console.log(numberFormatter.formatDecimal(10000)));

formatInteger

Formats number to integer localized format.

Example of usage:

import numberFormatter from 'orolocale/js/formatter/number';

// 10,000 depending on locale settings
console.log(numberFormatter.formatInteger(10000)));

formatPercent

Formats number to percent localized format.

Example of usage:

import numberFormatter from 'orolocale/js/formatter/number';

// 50% depending on locale settings
console.log(numberFormatter.formatPercent(.5)));

formatCurrency

Formats number to currency localized format. If the currency is not specified, then the default one is used.

Example of usage:

import numberFormatter from 'orolocale/js/formatter/number';

// ($50,000.45) depending on locale settings if default currency in USD
console.log(numberFormatter.formatCurrency(-50000.45)));

// €1,000.00 depending on locale settings
console.log(numberFormatter.formatCurrency(1000, 'EUR')));

unformat

Parses a number from a localized number string. Can be used to parse all styles of localized numbers.

Example of usage:

import numberFormatter from 'orolocale/js/formatter/number';

// 50000.45 depending on locale settings
console.log(numberFormatter.unformat('$50,000.45')));

// 0.95 depending on locale settings
console.log(numberFormatter.unformat('95%')));

// -1000000.456 depending on locale settings
console.log(numberFormatter.unformat('(1,000,000.456)')));

// NaN
console.log(numberFormatter.unformat('ssss')));