number_format()

La función number_format() de PHP formatea un número con miles agrupados y un número opcional fijo de decimales. Devuelve un string, lo que la convierte en la función ideal para mostrar precios, estadísticas y cualquier número que un humano vaya a leer. Es puramente de presentación: no cambia el valor subyacente, solo la forma en que se representa.

Este capítulo cubre la sintaxis, cada parámetro, cómo funciona el redondeo y los errores comunes a tener en cuenta.

Sintaxis

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

Parámetros

La función siempre devuelve un string, por lo que la salida está lista para imprimir o concatenar, pero no debe usarse para operaciones aritméticas posteriores.

Ejemplo básico

Con solo el número pasado como argumento, number_format() redondea a un número entero y añade comas entre los miles:

Salida:

1,235

La parte fraccionaria .56 provocó que el valor se redondeara hacia arriba a 1235, y se insertó una coma entre los miles.

Controlar los decimales

Pasa un segundo argumento para mantener un número fijo de decimales. Esto es lo que casi siempre se quiere para importes monetarios:

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

Salida:

1,234.57

El tercer decimal (7) se redondea en la segunda posición. Observa que el número de decimales es fijo incluso cuando el valor original tiene menos — number_format(5, 2) devuelve "5.00".

Separadores personalizados (formatos internacionales)

El tercer y cuarto argumento permiten cambiar los separadores. Muchos países europeos usan un punto para los miles y una coma para el punto decimal:

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

Salida:

1,234,567.89
1.234.567,89
1 234 567.89

Para eliminar completamente la agrupación de miles, pasa un string vacío como cuarto argumento:

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

Salida:

1234567.89

Cómo funciona el redondeo

number_format() redondea el valor a la precisión solicitada usando redondeo a la mitad alejándose de cero — el mismo comportamiento predeterminado que la función round(). Un .5 final se redondea hacia arriba en magnitud:

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

Salida:

3
1
-10

Errores comunes

• El resultado es un string, no un número. Añadir el separador de miles significa que "1,235" + 1 no se comportará como una operación aritmética. Si necesitas seguir calculando con el valor, formatealo solo en el momento en que lo muestres. Para convertir la entrada del usuario que contiene separadores de nuevo en un número, usa floatval() después de eliminar los caracteres de agrupación.
• Redondea, no trunca. number_format(9.999, 2) devuelve "10.00", no "9.99". Para cálculos monetarios, redondea los valores deliberadamente antes de formatearlos.
• Puede aparecer cero negativo. Números negativos muy pequeños pueden representarse como -0.00. Suma 0 al valor (o usa abs() en valores cercanos a cero) si necesitas evitarlo.
• Para moneda con reconocimiento de idioma (símbolos, reglas de idioma, formatos contables), considera usar NumberFormatter de PHP de la extensión intl en lugar de construir el string manualmente.

Funciones relacionadas

• round() — redondea un número a una precisión determinada y devuelve un float.
• sprintf() y printf() — formatean números (y otros valores) con marcadores de posición % como %.2f.
• floatval() — convierte un string de vuelta en un número de punto flotante.
• Funciones matemáticas de PHP — el conjunto más amplio de funciones numéricas.

Práctica