fprintf()

Introducción

La función fprintf() escribe una cadena formateada en un flujo — un archivo, php://stdout, php://stderr, o cualquier otro recurso de flujo abierto — y rellena sus marcadores de posición a partir de una lista de argumentos separados. La f del nombre proviene de file: a diferencia de printf(), que imprime directamente en la salida, fprintf() envía su resultado al flujo que elijas.

Es el miembro de la familia printf encargado de escribir en flujos. En comparación con vfprintf(), ambas realizan exactamente la misma tarea pero reciben sus valores de forma distinta: fprintf() toma cada valor como su propio argumento, mientras que vfprintf() toma un único array. Recurre a fprintf() cuando tienes un puñado de valores separados para escribir en un archivo o en la consola.

Este capítulo cubre la sintaxis, los especificadores de formato, ejemplos ejecutables, cómo se compara con las funciones relacionadas y los errores más comunes.

Sintaxis

fprintf(resource $stream, string $format, mixed ...$values): int

Devuelve el número de caracteres escritos. En las versiones modernas de PHP, una llamada mal formada genera un error en lugar de devolver false, por lo que rara vez es necesario comprobar el valor de retorno para detectar fallos.

Especificadores de formato

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

Entre el % y la letra de tipo puedes añadir anchura, relleno y precisión — 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

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

<?php

$out = fopen("php://stdout", "w");

fprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", "John", 30, 1234.5);

fclose($out);

Salida:

Name: John | Age: 30 | Balance: 1234.50

Los tres argumentos 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 clásico es escribir líneas formateadas y alineadas en un archivo — por ejemplo, un pequeño registro:

<?php

$log = fopen("app.log", "a");

fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "INFO", "Server started");
fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "ERROR", "Disk full");

fclose($log);

echo file_get_contents("app.log");

Salida:

[2026-07-02] INFO  Server started
[2026-07-02] ERROR Disk full

%-5s alinea el nivel a la izquierda en una columna de 5 caracteres, de modo que los mensajes comienzan en la misma posición sin importar si el nivel es INFO o ERROR. Abrir el archivo con el modo "a" (añadir) agrega cada línea sin truncar lo que ya hay. Cada llamada a fprintf() escribe una línea, tomando sus valores como argumentos separados.

fprintf() vs printf() vs vfprintf()

Estas tres funciones comparten exactamente las mismas reglas de cadena de formato y solo se diferencian en a dónde va el resultado y cómo se pasan los valores:

Así, fprintf() es printf() pero escribiendo en un flujo en lugar de en la salida, y es vfprintf() pero con argumentos separados en lugar de un array:

// Argumentos separados → se escriben en $stream
fprintf($stream, "%s is %d", $name, $age);

// Los mismos valores como array → se escriben en $stream
vfprintf($stream, "%s is %d", [$name, $age]);

Si solo quieres recuperar la cadena formateada en lugar de escribirla en algún sitio, usa sprintf(). Un uso habitual de fprintf() en scripts de línea de comandos es escribir diagnósticos en el flujo de error, manteniéndolos separados de la salida normal:

<?php

fprintf(STDERR, "Error: %s (code %d)\n", "connection refused", 111);

STDERR es una constante de flujo predefinida disponible en los scripts de PHP CLI, por lo que no es necesario abrirla previamente con fopen().

Errores comunes

• El flujo va primero. El recurso de flujo es el primer argumento; la cadena de formato es el segundo. Pasar el formato primero (como en printf()) es el error más frecuente al cambiar entre ambas funciones.
• El flujo debe ser grabable. Abrir un archivo con "r" (modo lectura) y pasarlo a fprintf() falla — usa un modo de escritura como "w" (truncar) o "a" (añadir).
• Escribe, no devuelve texto. El valor de retorno es el conteo de caracteres, no la cadena formateada — una confusión frecuente con sprintf().
• Pasar muy pocos argumentos genera un error. Suministrar menos valores de los que la cadena de formato tiene especificadores lanza un ArgumentCountError en PHP 8+; los valores sobrantes simplemente se ignoran.
• Escapa los signos de porcentaje literales como %%, de lo contrario PHP intenta leer el siguiente carácter como un especificador.

Conclusión

fprintf() formatea una cadena y la escribe en un flujo, tomando sus valores como argumentos separados. Es la herramienta indicada cuando quieres una salida precisa y columnar enviada a un archivo o a la consola — líneas de registro, informes o diagnósticos de CLI en php://stderr. Para las variantes relacionadas, consulta printf() (imprime en la salida), sprintf() (devuelve una cadena) y vfprintf() (mismo destino, pero recibe un array de valores).

Práctica