number_format() w PHP: separator tysięcy i ułamki

number_format($number, $decimals) zwraca liczbę jako string z separatorem tysięcy i stałą liczbą miejsc po przecinku: number_format(1234567.891, 2) zwraca "1,234,567.89". Z jednym argumentem zaokrągla do liczby całkowitej: number_format(1234567.891) to "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";

Cztery parametry

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

Trzeci argument to znak między częścią całkowitą a dziesiętną, czwarty to znak między grupami trzech cyfr. Każdy może być dowolnym stringiem, także pustym albo znakiem wielobajtowym. Zmień separatory poniżej, aby zobaczyć każdy styl:

<?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";

Dane locale (CLDR) używają dla francuskiego wąskiej twardej spacji (U+202F), a dla rosyjskiego twardej spacji (U+00A0), żeby liczba nigdy nie została rozbita na dwie linie. W HTML przekaż jako separator "\u{202F}" albo "\u{00A0}" zamiast zwykłej spacji.

Formatowanie liczby bez separatora tysięcy

Przekaż '' jako czwarty argument. Dostajesz zwykłą liczbę ze stałą liczbą miejsc po przecinku, czyli postać, której oczekują bramki płatności, eksporty CSV i wartości <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";

W ostatniej linii ważne jest round() przed rzutowaniem: 19.9 * 100 jest zapisane jako 1989.9999999999998, a samo (int) obcięłoby to do 1989.

Jak zaokrągla number_format

number_format() zaokrągla połówki od zera, tak jak round(), więc 0.5 staje się 1, a -2.5 staje się -3. Koryguje też drobny błąd binarny w wartościach takich jak 2.675, dlatego może się różnić od 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 nie da się zapisać dokładnie w systemie binarnym; zapisana wartość jest odrobinę mniejsza. sprintf() formatuje tę zapisaną wartość i dostaje 2.67, a number_format() i round() traktują ją jak 2.675, które napisałeś. Jeśli potrzebujesz konkretnej zasady zaokrąglania, sam najpierw wywołaj round(), floor() albo ceil() (zobacz zaokrąglanie i matematyka) i przekaż wynik do number_format().

Formatowanie kwot i innych walut

number_format() nic nie wie o walutach, więc symbol dodajesz sam. Znak minus umieszczaj przed symbolem i pamiętaj, że jen nie ma części dziesiętnej:

<?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";

Do wyjścia zależnego od locale, z właściwą pozycją symbolu dla każdego kraju, całą pracę wykonuje NumberFormatter z rozszerzenia intl:

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

Wymaga rozszerzenia intl, które nie wszędzie jest zainstalowane, więc przenośnym wyborem jest number_format() z własnym symbolem.

Wynik jest stringiem, a nie liczbą

To najczęstszy błąd z number_format(): sformatowanie wartości, a potem liczenie na niej. "1,234.50" nie jest stringiem liczbowym, więc PHP czyta tylko 1 przed przecinkiem:

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

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

Przekazanie takiego stringa z powrotem do number_format() jest jeszcze gorsze: rzuca TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. Do obliczeń trzymaj surową liczbę, a formatuj dopiero w chwili wypisywania. Jeśli dostajesz sformatowany string z formularza lub pliku, najpierw usuń separatory:

<?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);

Do dopełniania, wyrównania albo znaku plus przed liczbą użyj sprintf(); nie dodaje separatorów tysięcy, ale kontroluje szerokość i znak.