fputs()

¿Qué es la función fputs()?

La función fputs() escribe una string en un archivo abierto. Es la herramienta principal para guardar texto en disco en PHP: registros, exportaciones, archivos de configuración generados, etc.

El dato más importante sobre fputs() es que es un alias de fwrite() — las dos funciones son idénticas en todos los aspectos. PHP mantiene fputs() porque el nombre se lee como "file put string", lo que resulta familiar para programadores que vienen de C. El código nuevo generalmente prefiere fwrite(), pero ambas se comportan igual, por lo que todo lo que se explica aquí aplica a cualquiera de los dos nombres.

Sintaxis

fputs(resource $stream, string $data, ?int $length = null): int|false

• $stream — un puntero de archivo (un resource) devuelto por fopen(). Este es el archivo abierto en el que se escribe, no un nombre de archivo.
• $data — la string a escribir.
• $length — opcional. Si se proporciona, la escritura se detiene después de $length bytes, incluso si $data es más larga.

Devuelve el número de bytes escritos, o false en caso de error. Ten en cuenta que devuelve 0, no false, cuando no hay nada que escribir, por lo que siempre usa === al comprobar errores.

Cómo usar la función fputs()

Escribir en un archivo siempre sigue un patrón de tres pasos:

1. Abrir el archivo con fopen(), eligiendo un modo (ver más abajo).
2. Llamar a fputs() tantas veces como sea necesario.
3. Cerrar el archivo con fclose() para vaciar el búfer y liberar el manejador.

<?php

$file = fopen('myfile.txt', 'w');   // open for writing, truncating the file
fputs($file, "Hello, world!\n");    // write a line
fclose($file);                      // flush + release the handle

Después de ejecutar esto, myfile.txt contiene Hello, world! seguido de un salto de línea. El \n está dentro de comillas dobles, por lo que PHP lo convierte en un salto de línea real (un \n literal entre comillas simples se escribiría de forma literal).

Elegir el modo correcto de fopen()

El modo que se pasa a fopen() determina dónde escribe fputs() y si el contenido existente se conserva. Estos son los modos que permiten escritura:

Usa 'w' para sobreescribir y 'a' (append) para añadir a un registro sin perder lo que ya está ahí.

<?php

// Append three lines to a log; each run adds to the end.
$log = fopen('app.log', 'a');
fputs($log, "2026-06-21 user logged in\n");
fputs($log, "2026-06-21 report generated\n");
fclose($log);

Limitar cuánto se escribe

El tercer argumento opcional limita el número de bytes escritos. Es útil cuando solo quieres un prefijo de una cadena más larga:

<?php

$file = fopen('clip.txt', 'w');
$written = fputs($file, 'Hello, world!', 5);  // write only the first 5 bytes
fclose($file);

echo $written;   // 5  — the file now contains "Hello"

$written es 5, y clip.txt contiene solo Hello.

Siempre verifica el valor de retorno

Una escritura puede fallar: disco lleno, archivo de solo lectura o un manejador cerrado. Dado que fputs() puede devolver 0 de forma legítima, comprueba el resultado con la comparación estricta === false:

<?php

$file = fopen('out.txt', 'w');

if (fputs($file, 'data') === false) {
    echo 'Write failed!';
} else {
    echo 'Write succeeded.';
}

fclose($file);

Esto imprime Write succeeded. y evita el error clásico donde if (!fputs(...)) trata erróneamente una escritura válida de 0 bytes como un error.

fputs() vs. file_put_contents()

fputs() requiere un manejador abierto y es ideal cuando se escribe de forma incremental (muchas escrituras pequeñas, como un bucle de registro). Cuando simplemente quieres volcar una string completa en un archivo de una sola vez, file_put_contents() realiza la apertura, escritura y cierre en una sola llamada:

<?php

// Equivalent one-liner — no fopen()/fclose() needed.
file_put_contents('myfile.txt', "Hello, world!\n");

Usa fputs()/fwrite() cuando necesites control sobre el manejador (añadir en múltiples llamadas, escrituras parciales); usa file_put_contents() para escrituras únicas completas.

Resumen

• fputs() es un alias de fwrite() — mismo comportamiento, dos nombres.
• Escribe en un puntero de archivo abierto de fopen(), así que siempre emparéjalo con fclose().
• Devuelve el número de bytes, o false en caso de error — comprueba con === false.
• Elige 'w' para sobreescribir y 'a' para añadir; una longitud opcional limita los bytes escritos.
• Para una escritura única de archivo completo, prefiere file_put_contents(). Para leer los datos de vuelta, consulta fgets() y fread().

Práctica