number_format()

La fonction PHP number_format() formate un nombre avec des milliers groupés et un nombre optionnel de décimales fixes. Elle retourne une chaîne de caractères, ce qui en fait la fonction incontournable pour afficher des prix, des statistiques et tout nombre destiné à être lu par un humain. Elle concerne uniquement la présentation : elle ne modifie pas la valeur sous-jacente, seulement la façon dont elle est rendue.

Ce chapitre couvre la syntaxe, chaque paramètre, le fonctionnement de l'arrondi et les pièges courants à éviter.

Syntaxe

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

Paramètres

La fonction retourne toujours une chaîne, donc le résultat est prêt à être affiché ou concaténé, mais ne doit pas être utilisé pour d'autres calculs arithmétiques.

Exemple de base

En ne passant que le nombre, number_format() arrondit à un nombre entier et ajoute des virgules entre les milliers :

Résultat :

1,235

La partie fractionnaire .56 a provoqué un arrondi à 1235, et une virgule a été insérée entre les milliers.

Contrôler les décimales

Passez un deuxième argument pour conserver un nombre fixe de décimales. C'est presque toujours ce que vous voulez pour les montants :

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

Résultat :

1,234.57

La troisième décimale (7) est arrondie dans la deuxième position. Notez que le nombre de décimales est fixe même si la valeur d'origine en a moins — number_format(5, 2) retourne "5.00".

Séparateurs personnalisés (formats internationaux)

Les troisième et quatrième arguments permettent de changer les séparateurs. De nombreuses locales européennes utilisent un point pour les milliers et une virgule pour le séparateur décimal :

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

Résultat :

1,234,567.89
1.234.567,89
1 234 567.89

Pour supprimer entièrement le groupement des milliers, passez une chaîne vide comme quatrième argument :

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

Résultat :

1234567.89

Fonctionnement de l'arrondi

number_format() arrondit la valeur à la précision demandée en utilisant la règle arrondi à mi-distance vers zéro éloigné — le même comportement par défaut que la fonction round(). Un .5 terminal s'arrondit vers le haut en valeur absolue :

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

Résultat :

3
1
-10

Pièges courants

• Le résultat est une chaîne, pas un nombre. L'ajout du séparateur de milliers fait que "1,235" + 1 ne se comportera pas comme une opération arithmétique. Si vous devez continuer à calculer avec la valeur, formatez-la uniquement au moment de l'affichage. Pour reconvertir une entrée utilisateur contenant des séparateurs en nombre, utilisez floatval() après avoir supprimé les caractères de groupement.
• Elle arrondit, elle ne tronque pas. number_format(9.999, 2) retourne "10.00", pas "9.99". Pour les calculs monétaires, arrondissez vos valeurs délibérément avant de les formater.
• Un zéro négatif peut apparaître. Les très petits nombres négatifs peuvent s'afficher comme -0.00. Ajoutez 0 à la valeur (ou utilisez abs() sur les valeurs proches de zéro) si vous devez éviter cela.
• Pour une devise tenant compte de la locale (symboles, règles de locale, formats comptables), envisagez d'utiliser le NumberFormatter de PHP de l'extension intl plutôt que de construire la chaîne manuellement.

Fonctions associées

• round() — arrondit un nombre à une précision donnée et retourne un float.
• sprintf() et printf() — formatent des nombres (et d'autres valeurs) avec des espaces réservés % tels que %.2f.
• floatval() — convertit une chaîne en nombre à virgule flottante.
• Fonctions mathématiques PHP — l'ensemble plus large des utilitaires numériques.

Exercice