vprintf()

Introducción

La función vprintf() en PHP genera una cadena formateada. Se comporta exactamente igual que printf(), excepto que los valores a sustituir se proporcionan como un único array en lugar de como argumentos separados. La v en el nombre proviene de vector (array).

Esta página cubre la sintaxis, los especificadores de formato que puedes usar, un conjunto de ejemplos ejecutables, las diferencias con funciones relacionadas y los errores comunes a evitar.

Usa vprintf() cuando los valores que necesitas formatear ya están en un array — por ejemplo, una fila de base de datos, el resultado de explode(), o una lista que construiste dinámicamente. Expandir ese array manualmente en printf($fmt, $row[0], $row[1], ...) es verboso y se rompe en el momento en que cambia el número de campos; vprintf($fmt, $row) maneja cualquier cantidad de forma limpia.

Sintaxis

vprintf(string $format, array $values): int|false

• $format — una cadena de plantilla que contiene uno o más marcadores de posición. Cada marcador comienza con un signo de porcentaje (%) seguido de un especificador de conversión como s (string), d (entero) o f (float).
• $values — un array cuyos elementos llenan los marcadores de posición, en orden. Debe contener al menos tantos elementos como marcadores de posición haya.

vprintf() imprime el resultado directamente y devuelve la longitud de la cadena de salida (un int), o false en caso de error. Si necesitas la cadena formateada como valor en lugar de imprimirla, usa vsprintf().

Ejemplo básico

Este es el caso más sencillo — tres marcadores de posición de string rellenos desde un array:

Esto generará:

I like apple, banana, and orange.

Cada %s es reemplazado, en orden, por el siguiente elemento de $values.

Especificadores de formato comunes

La cadena de formato es la misma que se usa en toda la familia printf. Los especificadores más útiles son:

También puedes controlar ancho, relleno, signo y precisión entre el % y el especificador:

<?php

// Pad an integer to 5 digits with leading zeros, show the sign, print binary.
vprintf("%05d / %+d / %b\n", [42, 7, 5]);

// Left-align in 10 columns, then right-align in 10 columns.
vprintf("%-10s|%10s|\n", ["left", "right"]);

// Money: two decimal places.
vprintf("Total: \$%01.2f\n", [49.9]);

Salida:

00042 / +7 / 101
left      |     right|
Total: $49.90

Reutilizar un valor con numeración de argumentos

Puedes hacer referencia a un elemento específico del array más de una vez con la sintaxis de intercambio %n$, donde n es la posición basada en 1:

<?php

vprintf("Hex of %1\$d is %1\$x\n", [255]);

Salida:

Hex of 255 is ff

Aquí %1$d y %1$x leen ambos el primer elemento del array (255) y lo formatean como decimal y hexadecimal respectivamente.

Usar el valor de retorno

vprintf() devuelve el número de caracteres que imprimió, lo cual es útil para registros o comprobaciones de alineación:

<?php

$len = vprintf("Total: \$%01.2f\n", [49.9]);
echo "Printed $len characters.\n";

Salida:

Total: $49.90
Printed 14 characters.

vprintf() vs. funciones relacionadas

Regla general: elige la versión con v cuando tus datos están en un array, y la versión con s cuando quieres que la cadena se devuelva en lugar de mostrarse.

Errores comunes

• Conteos incorrectos. Si el array tiene menos elementos que marcadores de posición, PHP lanza un ArgumentCountError (PHP 8+) o una advertencia en versiones anteriores. Los elementos extra del array simplemente se ignoran.
• Escapar $ en comillas dobles. Un signo de dólar literal antes de un dígito (como en $5) puede colisionar con la interpolación de variables de PHP. Usa cadenas de formato entre comillas simples o escápalo como \$, como se muestra arriba.
• Olvidar que imprime directamente. vprintf() escribe en la salida inmediatamente — su valor de retorno es una longitud, no la cadena. Usa vsprintf() para capturar el resultado.
• Arrays asociativos. Solo se usan los valores, en el orden en que están almacenados; las claves se ignoran. Pasa una lista (array numérico y secuencial) para evitar sorpresas.

Práctica