PHP number_format(): separatore delle migliaia e decimali

number_format($number, $decimals) restituisce il numero come stringa con un separatore delle migliaia e un numero fisso di decimali: number_format(1234567.891, 2) restituisce "1,234,567.89". Con un solo argomento arrotonda a un numero intero: number_format(1234567.891) vale "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";

I quattro parametri

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

Il terzo argomento è il carattere tra la parte intera e i decimali, il quarto il carattere tra i gruppi di tre cifre. Entrambi possono essere qualsiasi stringa, anche vuota o un carattere multibyte. Modifica i separatori qui sotto per vedere ogni stile:

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

I dati di localizzazione (CLDR) usano uno spazio stretto non separabile (U+202F) per il francese e uno spazio non separabile (U+00A0) per il russo, così un numero non va mai a capo su due righe. In HTML, passa "\u{202F}" o "\u{00A0}" come separatore invece di un semplice spazio.

Formattare un numero senza separatore delle migliaia

Passa '' come quarto argomento. Ottieni un numero semplice con un numero fisso di decimali, la forma che si aspettano i gateway di pagamento, le esportazioni CSV e i valori di <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";

Nell'ultima riga, round() prima del cast conta: 19.9 * 100 viene memorizzato come 1989.9999999999998, e (int) da solo lo taglierebbe a 1989.

Come arrotonda number_format

number_format() arrotonda la metà lontano dallo zero, come fa round(), quindi 0.5 diventa 1 e -2.5 diventa -3. Corregge anche il minuscolo errore binario di valori come 2.675, ed è per questo che può non essere d'accordo con 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 non si può memorizzare esattamente in binario; il valore memorizzato è appena sotto. sprintf() formatta quel valore memorizzato e ottiene 2.67, mentre number_format() e round() lo trattano come il 2.675 che hai scritto. Se ti serve una regola di arrotondamento precisa, chiama prima tu round(), floor() o ceil() (vedi arrotondamenti e matematica) e passa il risultato a number_format().

Formattare denaro e altre valute

number_format() non sa nulla delle valute, quindi il simbolo lo aggiungi tu. Metti il segno negativo prima del simbolo, e ricorda che lo yen non ha decimali:

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

Per un output che segue il locale, con la posizione giusta del simbolo per ogni paese, il NumberFormatter dell'estensione intl fa tutto il lavoro:

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

Richiede l'estensione intl, che non è installata ovunque, quindi number_format() con il tuo simbolo è la scelta portabile.

Il risultato è una stringa, non un numero

È il bug più comune con number_format(): formattare un valore e poi farci dei calcoli. "1,234.50" non è una stringa numerica, quindi PHP legge solo l'1 prima della virgola:

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

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

Passare una stringa del genere di nuovo a number_format() è peggio: lancia TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. Tieni il numero grezzo per i calcoli e formatta solo nel momento in cui stampi. Se ricevi una stringa già formattata da un form o da un file, togli prima i separatori:

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

Per il riempimento, l'allineamento o un segno più davanti al numero, usa invece sprintf(); non aggiunge i separatori delle migliaia, ma controlla larghezza e segno.