PHP number_format(): разделитель тысяч и знаки после запятой

number_format($number, $decimals) возвращает число строкой с разделителем тысяч и фиксированным числом знаков после запятой: number_format(1234567.891, 2) возвращает "1,234,567.89". С одним аргументом функция округляет до целого: number_format(1234567.891) даёт "1,234,568".

<?php
$amount = 1234567.891;

echo number_format($amount), "\n";            // no decimals
echo number_format($amount, 2), "\n";         // 2 decimals
echo number_format($amount, 2, ',', '.'), "\n"; // European style
echo number_format(0.129, 2), "\n";
echo number_format(-1234.567, 1), "\n";

Четыре параметра

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

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

<?php
$n = 1234567.891;

echo number_format($n, 2, '.', ','), "  US, UK, Japan\n";
echo number_format($n, 2, ',', '.'), "  Germany, Spain, Italy, Brazil\n";
echo number_format($n, 2, ',', ' '), "  France, Russia, Poland\n";
echo number_format($n, 2, '.', "'"), "  Switzerland\n";
echo number_format($n, 2, '.', ''), "  no separator\n";

Данные локалей (CLDR) используют узкий неразрывный пробел (U+202F) для французского и неразрывный пробел (U+00A0) для русского, чтобы число никогда не переносилось на две строки. В HTML передавайте разделителем "\u{202F}" или "\u{00A0}" вместо обычного пробела.

Число без разделителя тысяч

Передайте '' четвёртым аргументом. Получится простое число с фиксированным числом знаков после запятой, именно такое ждут платёжные шлюзы, экспорт в CSV и значения <input type="number">:

<?php
$prices = [5, 19.9, 1234.5];

foreach ($prices as $p) {
    echo number_format($p, 2, '.', ''), "\n";
}

// Cents as an integer, for APIs that want the smallest unit
echo (int) round(19.9 * 100), "\n";

В последней строке важен round() перед приведением: 19.9 * 100 хранится как 1989.9999999999998, и один (int) обрезал бы его до 1989.

Как округляет number_format

number_format() округляет половину от нуля, как round(), поэтому 0.5 становится 1, а -2.5 становится -3. Ещё она исправляет крошечную двоичную ошибку в значениях вроде 2.675, поэтому может расходиться со sprintf('%.2f'):

<?php
foreach ([0.5, 1.5, 2.5, -2.5] as $x) {
    echo $x, " => ", number_format($x), "\n";
}

echo "\n";
echo number_format(2.675, 2), "  number_format\n";
echo sprintf('%.2f', 2.675), "  sprintf\n";
echo round(2.675, 2), "  round\n";

// PHP 8.3: negative decimals round to tens, hundreds, thousands
echo number_format(1234567, -3), "\n";

2.675 нельзя точно сохранить в двоичном виде; сохранённое значение чуть меньше. sprintf() форматирует это сохранённое значение и получает 2.67, а number_format() и round() считают его тем 2.675, которое вы написали. Если нужно определённое правило округления, сами вызовите round(), floor() или ceil() (смотрите округление и математику) и передайте результат в number_format().

Деньги и другие валюты

number_format() ничего не знает о валютах, поэтому символ добавляйте сами. Ставьте знак минус перед символом и помните, что у иены нет дробной части:

<?php
function money(float $amount, string $symbol = '$'): string
{
    $sign = $amount < 0 ? '-' : '';
    return $sign . $symbol . number_format(abs($amount), 2);
}

echo money(1499.5), "\n";
echo money(-20), "\n";
echo money(1234.5, '€'), "\n";

// Japanese yen: no decimals, 円 after the number
echo number_format(1980), "円\n";
echo '¥' . number_format(128000), "\n";

Для вывода с учётом локали и правильным положением символа в каждой стране всю работу делает NumberFormatter из расширения intl:

$fmt = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
echo $fmt->formatCurrency(1234.5, 'EUR'); // 1.234,50 € (a no-break space before €)

Ему нужно расширение intl, которое установлено не везде, поэтому number_format() со своим символом это переносимый выбор.

Результат это строка, а не число

Самая частая ошибка с number_format(): отформатировать значение, а потом с ним считать. "1,234.50" не числовая строка, поэтому PHP читает только 1 до запятой:

<?php
echo number_format(1234.5, 2) + 1;

Warning: A non-numeric value encountered in /home/index.php on line 2
2

Передать такую строку обратно в number_format() ещё хуже: она выбрасывает TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. Храните исходное число для математики и форматируйте только в момент вывода. Если отформатированная строка пришла из формы или файла, сначала уберите разделители:

<?php
$total = 1234.5;
$display = number_format($total, 2);      // for output only

echo $display, "\n";
echo number_format($total + 100, 2), "\n"; // math on the number, then format

// Turning "1,234.50" back into a float
$input = '1,234.50';
$value = (float) str_replace(',', '', $input);
var_dump($value);

// European input "1.234,50"
$eu = '1.234,50';
$value = (float) str_replace(['.', ','], ['', '.'], $eu);
var_dump($value);

Для дополнения, выравнивания или знака плюс перед числом используйте sprintf(): она не добавляет разделители тысяч, но управляет шириной и знаком.