The NumberFormatter class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Введение

Программы хранят и оперируют числами в двоичном представлении, которое не зависит от текущих региональных настроек. При выводе на экран или печати числа программы преобразовывают числа в строку по правилам, которые соответствуют региональным параметрам. Число 12345.67 в локали US программа выведет как «12,345.67», во французской локали — как «12 345,67» и как «12.345,67» в немецкой.

Методы класса NumberFormatter форматируют числа, денежные единицы и процентные величины в представлении заданных по умолчанию региональных настроек. Класс NumberFormatter чувствителен к региональным параметрам, поэтому придётся создавать новый экземпляр класса NumberFormatter для каждой локали. Методы класса NumberFormatter форматируют числа примитивного типа наподобие double и выводят число в виде строки, формат которой зависит от текущих региональных параметров.

Для валют можно использовать тип формата денежной единицы, который возвращает строку с отформатированным числом и символом валюты. Естественно, класс NumberFormatter не знает об обменных курсах, так что выводимое число будет одинаковым независимо от установленной валюты. То есть одинаковые числа имеют разную денежную стоимость, которая зависит от настроек региональной валюты. Для числа 9988776.65 результат будет таким:

  • 9 988 776,65 € для Франции
  • 9.988.776,65 € для Германии
  • $9,988,776.65 для США

Чтобы отформатировать процентную величину, создают средство форматирования с типом процентного формата, который соответствует текущим региональным настройкам. Такое средство форматирования отобразит десятичную дробь числа 0.75 как 75 %.

Для более сложного форматирования, например записи чисел в виде текста, работают правила средства форматирования по преобразованию чисел в текст.

Обзор класса

class NumberFormatter {
/* Константы */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ACCOUNTING;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Методы */
public __construct(string $locale, int $style, ?string $pattern = null)
public static create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter
public format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false
public formatCurrency(float $amount, string $currency): string|false
public getAttribute(int $attribute): int|float|false
public getErrorCode(): int
public getSymbol(int $symbol): string|false
public getTextAttribute(int $attribute): string|false
public parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false
public parseCurrency(string $string, string &$currency, int &$offset = null): float|false
public setAttribute(int $attribute, int|float $value): bool
public setPattern(string $pattern): bool
public setSymbol(int $symbol, string $value): bool
public setTextAttribute(int $attribute, string $value): bool
}

Предопределённые константы

Типы форматирования

Эти стили используются функцией numfmt_create() для определения типа форматирования.

NumberFormatter::PATTERN_DECIMAL int
Формат с десятичной точкой заданный шаблоном
NumberFormatter::DECIMAL int
Формат с десятичной точкой
NumberFormatter::CURRENCY int
денежный формат
NumberFormatter::PERCENT int
Процентный формат
NumberFormatter::SCIENTIFIC int
Научный формат
NumberFormatter::SPELLOUT int
Разобранный формат на основе правил
NumberFormatter::ORDINAL int
Числительный формат на основе правил
NumberFormatter::DURATION int
Формат длительности на основе правил
NumberFormatter::PATTERN_RULEBASED int
Формат на основе правил по шаблону
NumberFormatter::CURRENCY_ACCOUNTING int
Формат валюты для учёта, например, ($3.00) для отрицательной суммы в валюте вместо -$3.00. Доступно с PHP 7.4.1 и ICU 53.
NumberFormatter::DEFAULT_STYLE int
Формат по умолчанию для локали
NumberFormatter::IGNORE int
Псевдоним для PATTERN_DECIMAL

Спецификаторы числового формата

Эти константы определяют, как будут разобраны или отформатированы числа. Их необходимо передавать функциям numfmt_format() и numfmt_parse().

NumberFormatter::TYPE_DEFAULT int
Тип определяется типом переменной
NumberFormatter::TYPE_INT32 int
Форматирование или разбор как 32-битного целого
NumberFormatter::TYPE_INT64 int
Форматирование или разбор как 64-битного целого
NumberFormatter::TYPE_DOUBLE int
Форматирование или разбор как числа с плавающей точкой
NumberFormatter::TYPE_CURRENCY int
Форматирование или разбор как значения денежной единицы. Устарел с PHP 8.3.0

Атрибуты числового формата

Атрибут формата чисел для numfmt_get_attribute() и numfmt_set_attribute().

NumberFormatter::PARSE_INT_ONLY int
Разбирать только целые.
NumberFormatter::GROUPING_USED int
Использовать группирующий разделитель.
NumberFormatter::DECIMAL_ALWAYS_SHOWN int
Всегда показывать десятичную точку.
NumberFormatter::MAX_INTEGER_DIGITS int
Максимальное число целых цифр.
NumberFormatter::MIN_INTEGER_DIGITS int
Минимальное число целых цифр.
NumberFormatter::INTEGER_DIGITS int
Целых цифр.
NumberFormatter::MAX_FRACTION_DIGITS int
Максимальное число цифр после запятой.
NumberFormatter::MIN_FRACTION_DIGITS int
Минимальное число цифр после запятой.
NumberFormatter::FRACTION_DIGITS int
Число цифр после запятой.
NumberFormatter::MULTIPLIER int
Множитель.
NumberFormatter::GROUPING_SIZE int
Размер группировки.
NumberFormatter::ROUNDING_MODE int
Режим округления.
NumberFormatter::ROUNDING_INCREMENT int
Приращение округления.
NumberFormatter::FORMAT_WIDTH int
Ширина на которую будет дополнен вывод format().
NumberFormatter::PADDING_POSITION int
Позиция с которой дополнение будет иметь место. Смотрите описание констант дополнения.
NumberFormatter::SECONDARY_GROUPING_SIZE int
Вторичный размер группировки.
NumberFormatter::SIGNIFICANT_DIGITS_USED int
Использовать значащие цифры.
NumberFormatter::MIN_SIGNIFICANT_DIGITS int
Минимальное количество значащих цифр.
NumberFormatter::MAX_SIGNIFICANT_DIGITS int
Максимальное количество значащих цифр.
NumberFormatter::LENIENT_PARSE int
Режим снисходительны синтаксического анализа для основанных на правилах форматов.

Текстовые атрибуты числового формата

Атрибуты текста форматирования чисел, используются в функциях numfmt_get_text_attribute() и numfmt_set_text_attribute().

NumberFormatter::POSITIVE_PREFIX int
Положительный префикс.
NumberFormatter::POSITIVE_SUFFIX int
Положительный суффикс.
NumberFormatter::NEGATIVE_PREFIX int
Отрицательный префикс.
NumberFormatter::NEGATIVE_SUFFIX int
Отрицательный суффикс.
NumberFormatter::PADDING_CHARACTER int
Символ для дополнения строки.
NumberFormatter::CURRENCY_CODE int
Код денежной единицы ISO.
NumberFormatter::DEFAULT_RULESET int
Набор правил по умолчанию. Доступно только для форматирования на основе правил.
NumberFormatter::PUBLIC_RULESETS int
Публичный набор правил. Доступно только для форматирования на основе правил. Этот атрибут доступен только на чтение. Публичный набор правил возвращается в виде строки, в которой каждый набор правил отделен точкой с запятой (;).

Спецификаторы формата символов

Символы форматирования чисел для numfmt_get_symbol() и numfmt_set_symbol().

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL int
Десятичный разделитель.
NumberFormatter::GROUPING_SEPARATOR_SYMBOL int
Разделитель групп.
NumberFormatter::PATTERN_SEPARATOR_SYMBOL int
Символ разделителя в шаблона.
NumberFormatter::PERCENT_SYMBOL int
Символ процента.
NumberFormatter::ZERO_DIGIT_SYMBOL int
Ноль.
NumberFormatter::DIGIT_SYMBOL int
Символ представляющий цифру в шаблоне.
NumberFormatter::MINUS_SIGN_SYMBOL int
Знак минус.
NumberFormatter::PLUS_SIGN_SYMBOL int
Знак плюс.
NumberFormatter::CURRENCY_SYMBOL int
Символ обозначения денежной единицы.
NumberFormatter::INTL_CURRENCY_SYMBOL int
The international currency symbol.
NumberFormatter::MONETARY_SEPARATOR_SYMBOL int
Денежный разделитель.
NumberFormatter::EXPONENTIAL_SYMBOL int
Символ степени десяти.
NumberFormatter::PERMILL_SYMBOL int
Символ промилле.
NumberFormatter::PAD_ESCAPE_SYMBOL int
Экранирование символа заполнителя.
NumberFormatter::INFINITY_SYMBOL int
Символ бесконечности.
NumberFormatter::NAN_SYMBOL int
Символ NAN (Not-a-number, не-число).
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL int
Символ значащей цифры.
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL int
Разделитель групп для денежного формата.

Режимы округления

Режимы округления для numfmt_get_attribute() и numfmt_set_attribute() с атрибутом NumberFormatter::ROUNDING_MODE.

NumberFormatter::ROUND_AWAY_FROM_ZERO
Псевдоним константы NumberFormatter::ROUND_UP.
NumberFormatter::ROUND_CEILING int
Округление в сторону положительной бесконечности.
NumberFormatter::ROUND_DOWN int
Округление вниз.
NumberFormatter::ROUND_FLOOR int
Округление в сторону отрицательной бесконечности.
NumberFormatter::ROUND_HALFDOWN int
Округление в сторону "ближайшего соседа" кроме случаев, когда они на одинаковом расстоянии. В этом случае округление вниз.
NumberFormatter::ROUND_HALFEVEN int
Округление в сторону "ближайшего соседа" кроме случаев, когда они на одинаковом расстоянии. В этом случае округление к чётному значению.
NumberFormatter::ROUND_HALFODD
Режим округления в сторону «нечётного соседа».
NumberFormatter::ROUND_HALFUP int
Округление в сторону "ближайшего соседа" кроме случаев, когда они на одинаковом расстоянии. В этом случае округление вверх.
NumberFormatter::ROUND_TOWARD_ZERO
Псевдоним константы NumberFormatter::ROUND_DOWN.
NumberFormatter::ROUND_UP int
Округление вверх.

Спецификаторы дополнения

Значения позиции дополнения для функций numfmt_get_attribute() и numfmt_set_attribute() с атрибутом NumberFormatter::PADDING_POSITION.

NumberFormatter::PAD_AFTER_PREFIX int
Символы дополнения вставляются после префикса.
NumberFormatter::PAD_AFTER_SUFFIX int
Символы дополнения вставляются после суффикса.
NumberFormatter::PAD_BEFORE_PREFIX int
Символы дополнения вставляются до префикса.
NumberFormatter::PAD_BEFORE_SUFFIX int
Символы дополнения вставляются до суффикса.

Список изменений

Версия Описание
8.4.0 Константы класса стали типизированными.

Содержание

Добавить

Примечания пользователей 8 notes

up
49
giorgio dot liscio at email dot it
13 years ago
this class seems to be painful: it is not, formatting and parsing are highly customizable, but what you probably need is really simple:

if you want to localize a number use:

<?php
$a
= new \NumberFormatter("it-IT", \NumberFormatter::DECIMAL);
echo
$a->format(12345.12345) . "<br>"; // outputs 12.345,12
$a->setAttribute(\NumberFormatter::MIN_FRACTION_DIGITS, 0);
$a->setAttribute(\NumberFormatter::MAX_FRACTION_DIGITS, 100); // by default some locales got max 2 fraction digits, that is probably not what you want
echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12345
?>

if you want to print money use:

<?php
$a
= new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);
echo
$a->format(12345.12345) . "<br>"; // outputs €12.345,12
?>

if you have money data stored as (for example) US dollars and you want to print them using the it-IT notation, you need to use

<?php
$a
= new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);
echo
$a->formatCurrency(12345, "USD") . "<br>"; // outputs $ 12.345,00 and it is formatted using the italian notation (comma as decimal separator)
?>

another useful example about currency (how to obtain the currency name by a locale string):

<?php
$frontEndFormatter
= new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);
$adminFormatter = new \NumberFormatter("en-US", \NumberFormatter::CURRENCY);
$symbol = $adminFormatter->getSymbol(\NumberFormatter::INTL_CURRENCY_SYMBOL); // got USD
echo $frontEndFormatter->formatCurrency(12345.12345, $symbol) . "<br>";
?>
up
3
jimbo2150 at gmail dot com
1 year ago
The NumberFormatter class can be used to convert integer numbers to Roman numerals without a custom function using an array of symbols and associated values:

<?php

function intToRomanNumeral(int $num) {
static
$nf = new NumberFormatter('@numbers=roman', NumberFormatter::DECIMAL);
return
$nf->format($num);
}

echo
intToRomanNumeral(2); // II

echo intToRomanNumeral(5); // V

echo intToRomanNumeral(10); // X

echo intToRomanNumeral(50); // L

echo intToRomanNumeral(57); // LVII
echo intToRomanNumeral(58); // LVIII

echo intToRomanNumeral(100); // C

echo intToRomanNumeral(150); // CL

echo intToRomanNumeral(1000); // M

echo intToRomanNumeral(10000); // ↂ

?>
up
2
stan at dragnev dot ca
4 years ago
Here's an example of how to use PATTERN_DECIMAL to print a number with two fraction digits, use () for negative numbers and pad to five characters to the left of the decimal point, using spaces as the padding character:

<?php

$fmt
= new NumberFormatter("en-CA", NumberFormatter::PATTERN_DECIMAL, "* #####.00 ;(* #####.00)");
echo
$fmt->format(-45.1);

// Outputs: " (45.10)"

?>

Note that the ; in the pattern denotes the beginning of a subpattern, which is used for negative numbers. Hence the brackets around the pattern after the semicolon.
up
0
Einenlum
11 months ago
Be aware that (at least with the locale 'fr-FR') NumberFormatter doesn't use spaces. It doesn't even use non breakable spaces (NBSP). It uses narrow non breakable spaces (NNBSP). This broke my tests.

<?php

$formatter
= new NumberFormatter(
'fr-FR',
NumberFormatter::DEFAULT_STYLE
);

$value = $formatter->format(100_000); // '100 000'

// If you want to replace narrow non breakable spaces with non breakable spaces:

str_replace("\u{202F}", "\u{00A0}", $value);

// If you want to replace it with a normal space

str_replace("\u{202F}", " ", $value);
up
2
sudheer at binaryvibes dot co dot in
13 years ago
Sample script to print number in English.

<?php
$f
= new NumberFormatter("en", NumberFormatter::SPELLOUT);
echo
$f->format(123456);

?>

Produces the result:
one hundred twenty-three thousand four hundred fifty-six
up
0
gwyneth dot llewelyn at gwynethllewelyn dot net
2 years ago
When using the `NumberFormatter` class for pretty-printing currency in PHP 7.3 and 8+, it's not clear from the documentation that you can use the empty string "" as the locale for the constructor, and that will retrieve the default locale (whatever it has been set to in your environment).

`formatCurrency()`, by contrast, does not accept the empty string for the default currency symbol; it will display a 'generic' currency symbol instead (¤).

Tested with PHP 7.4.30, 8.0.21, 8.1.8 under Ubuntu Linux and 8.1.8 under macOS Big Sur (11.6.8). I tried under other alternatives (e.g. Linux running on ARM chips, PHP 7.3.3) but sadly the `NumberFormatter` library does not seem to be present (or could not be found) on those systems...
up
-2
AF
4 years ago
Please pay attention to the Arabic decimal separator (https://en.wikipedia.org/wiki/Decimal_separator#Other_numeral_systems).

All the following conditions are true:
<?php
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) === '٫';
(new
\NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) == '٫';

(new
\NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) !== ',';
(new
\NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) != ',';
?>
up
-3
Joey
7 years ago
Be warned that this class sometimes lacks sufficient error output. I recently instantiated it while invalid pattern to the constructor.

php -r '$nf = new \NumberFormatter("tlh-KX.UTF8", \NumberFormatter::IGNORE, "{,,#;#}");var_dump($nf->format(5));'

Fatal error: Call to a member function format() on null in Command line code on line 1

Rather than emitting an error message or throwing an exception null is returned after calling new.

I'm not sure if it's fixed in PHP 7 but it's something to watch out for. Make sure you check your parameters very closely.
To Top