PHP number_format() : séparateur de milliers et décimales

number_format($number, $decimals) renvoie le nombre sous forme de chaîne avec un séparateur de milliers et un nombre fixe de décimales : number_format(1234567.891, 2) renvoie "1,234,567.89". Avec un seul argument, elle arrondit à l'entier : number_format(1234567.891) donne "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";

Les quatre paramètres

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

Le troisième argument est le caractère placé entre la partie entière et les décimales, le quatrième celui placé entre les groupes de trois chiffres. L'un et l'autre peuvent être n'importe quelle chaîne, y compris vide ou un caractère multioctet. Modifiez les séparateurs ci-dessous pour voir chaque style :

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

Les données de locale (CLDR) utilisent une espace fine insécable (U+202F) pour le français et une espace insécable (U+00A0) pour le russe, afin qu'un nombre ne soit jamais coupé sur deux lignes. En HTML, passez "\u{202F}" ou "\u{00A0}" comme séparateur au lieu d'une espace simple.

Formater un nombre sans séparateur de milliers

Passez '' en quatrième argument. Vous obtenez un nombre simple avec un nombre fixe de décimales, la forme qu'attendent les passerelles de paiement, les exports CSV et les valeurs d'un <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";

Pour la dernière ligne, le round() avant le cast compte : 19.9 * 100 est stocké comme 1989.9999999999998, et (int) seul le couperait à 1989.

Comment number_format arrondit

number_format() arrondit la moitié en s'éloignant de zéro, comme round(), donc 0.5 devient 1 et -2.5 devient -3. Elle corrige aussi la minuscule erreur binaire de valeurs comme 2.675, c'est pourquoi elle peut ne pas être d'accord avec 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 ne peut pas être stocké exactement en binaire ; la valeur stockée est très légèrement inférieure. sprintf() formate cette valeur stockée et obtient 2.67, alors que number_format() et round() la traitent comme le 2.675 que vous avez écrit. Si vous avez besoin d'une règle d'arrondi précise, appelez vous-même round(), floor() ou ceil() d'abord (voir arrondis et calculs) et passez le résultat à number_format().

Formater de l'argent et d'autres devises

number_format() ne sait rien des devises, vous ajoutez donc le symbole vous-même. Placez le signe moins avant le symbole, et souvenez-vous que le yen n'a pas de décimales :

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

Pour un affichage adapté à la locale, avec la bonne position du symbole dans chaque pays, le NumberFormatter de l'extension intl fait tout le travail :

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

Il demande l'extension intl, qui n'est pas installée partout, donc number_format() avec votre propre symbole est le choix portable.

Le résultat est une chaîne, pas un nombre

C'est le bug le plus courant avec number_format() : formater une valeur puis calculer avec. "1,234.50" n'est pas une chaîne numérique, donc PHP ne lit que le 1 avant la virgule :

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

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

Repasser une telle chaîne à number_format() est pire : elle lève TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. Gardez le nombre brut pour les calculs et ne formatez qu'au moment d'afficher. Si vous recevez une chaîne formatée depuis un formulaire ou un fichier, retirez d'abord les séparateurs :

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

Pour le remplissage, l'alignement ou un signe plus devant le nombre, utilisez plutôt sprintf() ; elle n'ajoute pas de séparateurs de milliers, mais elle contrôle la largeur et le signe.