number_format()

Функция PHP number_format() форматирует число с разделителями групп разрядов и необязательным фиксированным количеством знаков после запятой. Она возвращает строку, что делает её основным инструментом для отображения цен, статистики и любых чисел, предназначенных для чтения человеком. Функция предназначена исключительно для представления данных: она не изменяет само значение, а только его внешний вид.

В этой главе рассматриваются синтаксис, каждый параметр, принцип округления и типичные ошибки, на которые стоит обратить внимание.

Синтаксис

number_format(float $number, int $decimals = 0, string $decimal_separator = ".", string $thousands_separator = ",") : string

Параметры

Функция всегда возвращает строку, поэтому результат готов к выводу или конкатенации, но не должен использоваться в дальнейших арифметических операциях.

Базовый пример

Если передать только число, number_format() округлит его до целого и добавит запятые между группами тысяч:

Вывод:

1,235

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

Управление количеством знаков после запятой

Передайте второй аргумент, чтобы зафиксировать количество десятичных знаков. Именно это почти всегда нужно при работе с денежными суммами:

<?php
echo number_format(1234.567, 2);  // two decimal places
?>

Вывод:

1,234.57

Третий знак после запятой (7) был округлён во второй. Обратите внимание, что количество знаков фиксировано даже если у исходного значения их меньше — number_format(5, 2) вернёт "5.00".

Пользовательские разделители (международные форматы)

Третий и четвёртый аргументы позволяют изменить разделители. Во многих европейских локалях точка используется для групп тысяч, а запятая — для десятичной дроби:

<?php
$amount = 1234567.891;

echo number_format($amount, 2, ".", ",") . "\n";  // US / UK style
echo number_format($amount, 2, ",", ".") . "\n";  // German / Spanish style
echo number_format($amount, 2, ".", " ");         // space-grouped
?>

Вывод:

1,234,567.89
1.234.567,89
1 234 567.89

Чтобы полностью убрать группировку тысяч, передайте пустую строку в качестве четвёртого аргумента:

<?php
echo number_format(1234567.891, 2, ".", "");
?>

Вывод:

1234567.89

Как работает округление

number_format() округляет значение до заданной точности, используя правило округления половины от нуля — то же самое, что применяется по умолчанию в функции round(). Значение .5 на конце округляется вверх по модулю:

<?php
echo number_format(2.5) . "\n";   // 3
echo number_format(0.5) . "\n";   // 1
echo number_format(-9.5);         // -10
?>

Вывод:

3
1
-10

Типичные ошибки

• Результат — строка, а не число. Добавление разделителя тысяч означает, что "1,235" + 1 не будет работать как арифметика. Если вам нужно продолжать вычисления с этим значением, форматируйте его только в момент отображения. Чтобы преобразовать пользовательский ввод с разделителями обратно в число, используйте floatval() после удаления символов группировки.
• Функция округляет, а не усекает. number_format(9.999, 2) возвращает "10.00", а не "9.99". При работе с денежными суммами округляйте значения намеренно перед форматированием.
• Может появиться отрицательный ноль. Очень маленькие отрицательные числа могут отображаться как -0.00. Прибавьте 0 к значению (или используйте abs() для значений, близких к нулю), чтобы избежать этого.
• Для форматирования с учётом локали (символы валют, правила локали, бухгалтерские форматы) рассмотрите использование PHP NumberFormatter из расширения intl вместо ручного формирования строки.

Связанные функции

• round() — округлить число до заданной точности и получить обратно float.
• sprintf() и printf() — форматирование чисел (и других значений) с помощью заполнителей %, например %.2f.
• floatval() — преобразовать строку обратно в число с плавающей запятой.
• Математические функции PHP — более широкий набор числовых вспомогательных функций.

Практика