number_format()

La funzione PHP number_format() formatta un numero con migliaia raggruppate e un numero opzionale fisso di cifre decimali. Restituisce una stringa, il che la rende la funzione di riferimento per visualizzare prezzi, statistiche e qualsiasi numero destinato alla lettura umana. È puramente una funzione di presentazione: non modifica il valore sottostante, ma solo il modo in cui viene rappresentato.

Questo capitolo tratta la sintassi, ogni parametro, il funzionamento dell'arrotondamento e i comuni errori da tenere d'occhio.

Sintassi

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

Parametri

La funzione restituisce sempre una stringa, quindi l'output è pronto per essere stampato o concatenato, ma non dovrebbe essere usato per ulteriori operazioni aritmetiche.

Esempio base

Passando solo il numero, number_format() arrotonda a un numero intero e aggiunge le virgole tra le migliaia:

Output:

1,235

La parte frazionaria .56 ha fatto sì che il valore venisse arrotondato a 1235, e una virgola è stata inserita tra le migliaia.

Controllo delle cifre decimali

Passa un secondo argomento per mantenere un numero fisso di decimali. Questo è quasi sempre ciò che si vuole per i valori monetari:

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

Output:

1,234.57

La terza cifra decimale (7) viene arrotondata nella seconda posizione. Si noti che il numero di decimali è fisso anche quando il valore originale ne ha di meno — number_format(5, 2) restituisce "5.00".

Separatori personalizzati (formati internazionali)

Il terzo e il quarto argomento permettono di cambiare i separatori. Molte impostazioni locali europee usano il punto per le migliaia e la virgola per il separatore decimale:

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

Output:

1,234,567.89
1.234.567,89
1 234 567.89

Per rimuovere completamente il raggruppamento delle migliaia, passa una stringa vuota come quarto argomento:

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

Output:

1234567.89

Come funziona l'arrotondamento

number_format() arrotonda il valore alla precisione richiesta usando l'arrotondamento al valore assoluto maggiore — lo stesso comportamento predefinito della funzione round(). Un .5 finale viene arrotondato verso il valore assoluto maggiore:

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

Output:

3
1
-10

Errori comuni

• Il risultato è una stringa, non un numero. L'aggiunta del separatore delle migliaia fa sì che "1,235" + 1 non si comporti come un'operazione aritmetica. Se hai bisogno di continuare a calcolare con il valore, formattalo solo nel momento in cui lo visualizzi. Per convertire un input utente che contiene separatori di nuovo in un numero, usa floatval() dopo aver rimosso i caratteri di raggruppamento.
• Arrotonda, non tronca. number_format(9.999, 2) restituisce "10.00", non "9.99". Per i calcoli monetari, arrotonda i valori deliberatamente prima di formattarli.
• Può apparire lo zero negativo. Numeri negativi molto piccoli possono essere visualizzati come -0.00. Aggiungi 0 al valore (o usa abs() per valori vicini allo zero) se vuoi evitarlo.
• Per valute con riconoscimento della lingua (simboli, regole locali, formati contabili), considera di usare NumberFormatter dell'estensione intl di PHP invece di costruire la stringa manualmente.

Funzioni correlate

• round() — arrotonda un numero a una data precisione e restituisce un float.
• sprintf() e printf() — formattano numeri (e altri valori) con i segnaposto % come %.2f.
• floatval() — converte una stringa in un numero in virgola mobile.
• Funzioni matematiche PHP — l'insieme più ampio di helper numerici.

Pratica