vfprintf()

Introducción

La función vfprintf() escribe una cadena formateada en un flujo — como un archivo o la salida estándar — y toma sus valores de un array en lugar de una lista de argumentos separados. La v inicial proviene de vector (un array de argumentos); la f proviene de file (apunta a un flujo).

En resumen, vfprintf() es a fprintf() lo que vsprintf() es a sprintf(): realiza el mismo formateo, pero le pasas un único array en lugar de enumerar cada argumento. Es la función que se usa cuando los valores ya están reunidos en un array.

Este capítulo cubre la sintaxis, los especificadores de formato, ejemplos ejecutables, cuándo elegirla sobre las alternativas y los errores más comunes.

Sintaxis

vfprintf(resource $stream, string $format, array $values): int

Devuelve el número de caracteres escritos. En la mayoría de las versiones de PHP, una llamada mal formada genera un error en lugar de devolver false, por lo que normalmente no se verifica el valor de retorno para detectar fallos.

Especificadores de formato

La cadena $format mezcla texto literal con marcadores de posición que comienzan con %. Los especificadores más comunes son:

Puedes añadir anchura, relleno y precisión entre el % y la letra de tipo — por ejemplo %05d (rellena un entero a 5 dígitos con ceros) o %.2f (dos decimales). Un % literal debe escribirse como %%.

Ejemplo: escribir en la salida estándar

Usar el flujo php://stdout permite ver el resultado de inmediato, lo que facilita probar vfprintf():

<?php

$out    = fopen("php://stdout", "w");
$values = ["John", 30, 1234.5];

vfprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", $values);

fclose($out);

Salida:

Name: John | Age: 30 | Balance: 1234.50

Los tres elementos del array rellenan %s, %d y %.2f en orden: la cadena se imprime tal cual, %d descarta la parte decimal de un entero y %.2f formatea el número de punto flotante a exactamente dos decimales.

Ejemplo: escribir en un archivo

El caso de uso original es escribir líneas formateadas en un archivo. Aquí se añaden tres filas tomadas de un array de registros:

<?php

$records = [
    ["Alice", 95],
    ["Bob",   82],
    ["Carol", 77],
];

$file = fopen("scores.txt", "w");

foreach ($records as $row) {
    vfprintf($file, "%-10s %3d%%\n", $row);
}

fclose($file);

echo file_get_contents("scores.txt");

Salida:

Alice       95%
Bob         82%
Carol       77%

%-10s alinea el nombre a la izquierda en una columna de 10 caracteres, %3d alinea la puntuación a la derecha en una columna de 3 caracteres y %% imprime el signo de porcentaje literal. Como cada $row ya es un array, vfprintf() lo consume directamente — sin necesidad de desempaquetar los valores.

¿Por qué usar un array? vfprintf() vs fprintf()

fprintf() toma sus valores como argumentos separados:

fprintf($file, "%s is %d", $name, $age);

vfprintf() toma los mismos valores en un único array:

vfprintf($file, "%s is %d", [$name, $age]);

Usa vfprintf() cuando los valores ya están en un array — por ejemplo, una fila de base de datos, una línea CSV analizada o argumentos construidos en un bucle — para no tener que desempaquetarlos con el operador de propagación (...$row). Si simplemente quieres obtener la cadena formateada en lugar de escribirla en un flujo, usa vsprintf(); para imprimir directamente en la salida sin un recurso de flujo, usa vprintf().

Errores comunes

• El array debe tener al menos tantos elementos como especificadores. Tener pocos valores provoca un ArgumentCountError (PHP 8+); los valores extra simplemente se ignoran.
• El orden importa. Los elementos se consumen posicionalmente, en el orden del array. Para referenciar un elemento específico sin importar el orden, usa marcadores numerados como %1$s y %2$d.
• Escribe, no devuelve texto. El valor de retorno es un conteo de caracteres, no la cadena formateada — una confusión frecuente con vsprintf().
• El flujo debe ser grabable. Abrir un archivo con "r" (modo lectura) y pasarlo a vfprintf() falla.

Conclusión

vfprintf() formatea una cadena y la escribe en un flujo, tomando sus valores de un array. Destaca cuando los datos ya están reunidos en un array y se quiere escribirlos en un archivo o en la salida estándar con un formato preciso y columnar. Para las variantes sin flujo, consulta vsprintf() (devuelve una cadena) y vprintf() (imprime directamente), y compara con fprintf() cuando los argumentos son valores separados en lugar de un array.

Práctica