PHP sprintf(): formatear strings, relleno y decimales

sprintf() devuelve una cadena construida a partir de un formato y una lista de valores: cada marcador % del formato se sustituye por el siguiente valor. sprintf('%s is %d years old', 'Ada', 36) devuelve "Ada is 36 years old". printf() acepta los mismos argumentos pero imprime el resultado en lugar de devolverlo.

<?php
$name = 'Ada';
$age = 36;
$price = 4.5;

$line = sprintf('%s is %d years old', $name, $age);
echo $line, "\n";

// Two decimals, always
echo sprintf('Total: %.2f EUR', $price), "\n";

// printf prints directly
printf("Order #%05d for %s\n", 42, $name);

Los marcadores se rellenan en orden, de izquierda a derecha. %.2f muestra siempre dos decimales (4.50, no 4.5), y %05d rellena el número con ceros hasta cinco dígitos.

Los especificadores de formato

Un marcador es %, unos modificadores opcionales y luego una letra para el tipo:

Cambia los valores de abajo y vuelve a ejecutarlo:

<?php
echo sprintf('%s', 'PHP'), "\n";
echo sprintf('%d', 42.9), "\n";      // the decimals are cut off, not rounded
echo sprintf('%f', 1.5), "\n";
echo sprintf('%.2f', 1.5), "\n";
echo sprintf('%e', 1234.5678), "\n";
echo sprintf('%x %X', 255, 255), "\n";
echo sprintf('%o', 8), "\n";
echo sprintf('%b', 5), "\n";
echo sprintf('%08b', 5), "\n";       // binary padded to 8 bits
echo sprintf('%c', 65), "\n";
echo sprintf('%d%%', 50), "\n";
echo sprintf('%+d %+d', 5, -5), "\n"; // always show the sign

%d trunca un float hacia cero, así que 42.9 se convierte en 42. Si quieres 43, redondea primero: sprintf('%d', round(42.9)). Una cadena que no es un número, como 'abc', se convierte en 0 con %d.

Rellenar con ceros a la izquierda

Entre % y la letra puedes poner un carácter de relleno y un ancho. %05d significa "rellena con 0 hasta un ancho de 5". Es la forma habitual de formatear números de pedido, IDs de factura, horas y fechas.

<?php
echo sprintf('%05d', 42), "\n";         // 00042
echo sprintf('%03d', 7), "\n";          // 007
echo sprintf('INV-%06d', 1234), "\n";   // INV-001234

// Times and dates from numbers
$h = 9; $m = 5; $s = 3;
echo sprintf('%02d:%02d:%02d', $h, $m, $s), "\n";
echo sprintf('%04d-%02d-%02d', 2026, 3, 14), "\n";

// A width smaller than the number never cuts it
echo sprintf('%03d', 123456), "\n";

El ancho es un mínimo. Un número más largo que el ancho se imprime completo.

%05.2f: ancho y decimales a la vez

Con floats, el ancho cuenta cada carácter del resultado, incluidos el punto decimal y el signo menos. Por eso %05.2f aplicado a 3.14159 da 03.14: cinco caracteres en total, dos de ellos tras el punto.

<?php
$pi = 3.14159;

echo sprintf('%05.2f', $pi), "\n";   // 5 characters in total
echo sprintf('%08.2f', $pi), "\n";   // 8 characters in total
echo sprintf('%.2f', $pi), "\n";     // no width, just 2 decimals
echo sprintf('%.0f', $pi), "\n";     // no decimals
echo sprintf('%.2f', 5), "\n";       // integers get decimals too
echo sprintf('%08.2f', -3.5), "\n";  // the minus sign counts

%f usa el separador decimal de la configuración regional actual (fijada con setlocale()), mientras que %F usa siempre un punto. Si tu código fija una configuración regional y necesitas un punto para JSON, CSV o una API, usa %F.

Alinear texto en columnas

Un ancho positivo alinea a la derecha, un - antes del ancho alinea a la izquierda, y ' seguido de un carácter fija un carácter de relleno personalizado. Combinados, alinean informes y tickets en texto plano.

<?php
$items = [
    ['Coffee', 2, 3.5],
    ['Croissant', 1, 2.25],
    ['Orange juice', 3, 4],
];

printf("%-14s %3s %8s\n", 'Item', 'Qty', 'Price');
printf("%'-27s\n", '');

$total = 0;
foreach ($items as [$name, $qty, $price]) {
    $line = $qty * $price;
    $total += $line;
    printf("%-14s %3d %8.2f\n", $name, $qty, $line);
}

printf("%'-27s\n", '');
printf("%-14s %12.2f\n", 'Total', $total);
printf("[%'*10s]\n", 'stars');

%-14s rellena el nombre del artículo por la derecha hasta 14 caracteres, %8.2f alinea el precio a la derecha en 8 caracteres y %'-27s con una cadena vacía imprime una línea de 27 guiones. %'*10s rellena con * en lugar de espacios.

Numerar los argumentos para reutilizarlos o reordenarlos

%1$s significa "el primer argumento como cadena" y %2$d "el segundo como entero". Los marcadores numerados te permiten usar un valor dos veces o cambiar el orden sin cambiar la lista de argumentos, algo que necesitan los traductores cuando el orden de las palabras cambia entre idiomas.

<?php
// Single quotes: in double quotes PHP would read $s as a variable
$format = '%1$s has %2$d new messages. Open them, %1$s?';
echo sprintf($format, 'Ada', 3), "\n";

// Same arguments, different order in the sentence
$en = 'Page %1$d of %2$d';
$ja = '全%2$dページ中%1$dページ目';
echo sprintf($en, 2, 10), "\n";
echo sprintf($ja, 2, 10), "\n";

// Modifiers go after the $
echo sprintf('%1$05.1f / %1$.3f', 2.71828), "\n";

vsprintf, printf y los valores de retorno

vsprintf() recibe los valores como un solo array, algo práctico cuando ya están en un array. printf() devuelve el número de bytes que imprimió, y vprintf() es la versión con array de printf().

<?php
$row = ['Ada', 'Lovelace', 1815];
echo vsprintf("%s %s was born in %d.\n", $row);

$bytes = printf("%s\n", 'Hello');
echo "printf printed $bytes bytes\n";

// Same result, two ways
echo sprintf('%.1f%%', 12.345), "\n";
printf("%.1f%%\n", 12.345);

El recuento de printf() incluye el salto de línea, así que "Hello\n" son 6 bytes. Con texto multibyte cuenta bytes, no caracteres.

Pocos argumentos lanzan un error

Desde PHP 8, un formato con más marcadores que valores lanza un ArgumentCountError en lugar de devolver false. Cuenta los marcadores % (sin contar %%) cuando veas este error.

<?php
// This throws an ArgumentCountError on purpose: 3 placeholders, 2 values
echo sprintf('%s bought %d items for %.2f', 'Ada', 3);

El mensaje cuenta la cadena de formato como un argumento: ArgumentCountError: 4 arguments are required, 3 given. Los argumentos de más se ignoran en silencio, así que el error contrario no aparece como error. Si el resultado de un sprintf parece incorrecto, imprime el formato junto a los valores. Cuando solo necesitas un separador de miles, number_format() es más sencillo que construirlo con sprintf. La lista completa de modificadores está en php.net.