fwrite()

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

fwrite() es una función integrada de PHP que escribe una cadena en un archivo abierto. La escritura comienza en la posición actual del puntero de archivo y avanza ese puntero en la cantidad de bytes escritos, de modo que las llamadas consecutivas se concatenan en lugar de sobreescribirse. Es la forma estándar de bajo nivel para escribir en archivos en PHP y también se conoce comúnmente con el alias fputs() (ambas son idénticas).

Esta página cubre la sintaxis, el argumento opcional length, los modos de archivo que controlan dónde y cómo se escriben los datos, los valores de retorno, el manejo de errores y las tareas cotidianas para las que usarás fwrite().

Sintaxis

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

Valor de retorno: el número de bytes realmente escritos, o false en caso de error. Dado que es posible una escritura parcial (menos bytes que strlen($data)) en algunos flujos, el código robusto verifica el valor de retorno en lugar de asumir el éxito.

Casi nunca necesitas el argumento length. fwrite($file, $data) ya escribe la cadena completa. Pasa una longitud solo cuando quieras truncar deliberadamente la salida a los primeros N bytes.

Un Ejemplo Básico

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'w');     // open for writing (truncates the file)

if ($file === false) {
    exit("Could not open $filename for writing");
}

$bytes = fwrite($file, "Hello, world!");
fclose($file);

echo "Wrote $bytes bytes."; // Wrote 13 bytes.

Siempre intervienen tres pasos:

1. Abrir el archivo con fopen() en un modo que permita escritura.
2. Llamar a fwrite() una o más veces para enviar datos al flujo.
3. Cerrar el archivo con fclose() para vaciar el búfer y liberar el manejador.

"Hello, world!" tiene 13 caracteres, por lo que fwrite() devuelve 13.

Modos de Archivo: Hacia Dónde Van los Bytes

El comportamiento de fwrite() está determinado casi por completo por el modo que pasaste a fopen(). Esta es la fuente de confusión más común, por lo que vale la pena memorizarla:

Si tu archivo queda vacío o pierde los datos del día anterior, casi con certeza lo abriste con 'w' cuando querías 'a'.

Añadir en Lugar de Sobreescribir

<?php

$log = fopen('app.log', 'a');           // 'a' keeps existing lines
fwrite($log, "User logged in\n");       // \n adds a newline
fwrite($log, "Order placed\n");
fclose($log);

Cada ejecución de este script añade dos líneas más a app.log en lugar de borrarlo.

Escribir Múltiples Líneas

fwrite() escribe exactamente los bytes que le das — no añade saltos de línea. Inclúyelos tú mismo con \n (entre comillas dobles, para que el escape sea interpretado):

<?php

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

$names = ['Alice', 'Bob', 'Carol'];
foreach ($names as $name) {
    fwrite($file, $name . PHP_EOL); // PHP_EOL = OS-correct line ending
}

fclose($file);

PHP_EOL se resuelve a \n en Unix/macOS y a \r\n en Windows, lo que mantiene la portabilidad de los archivos de texto.

Siempre Verifica el Valor de Retorno

Las condiciones de disco lleno, los problemas de permisos y los canales rotos hacen que las escrituras fallen o sean incompletas. Trata el valor de retorno como la fuente de verdad:

<?php

$file = fopen('report.txt', 'w');
if ($file === false) {
    throw new RuntimeException('Unable to open report.txt');
}

$data    = str_repeat('x', 1000);
$written = fwrite($file, $data);

if ($written === false || $written < strlen($data)) {
    fclose($file);
    throw new RuntimeException('Write failed or incomplete');
}

fclose($file);
echo "OK: $written bytes written";

fwrite() vs file_put_contents()

Para una escritura única y puntual, file_put_contents() es más conciso — abre, escribe y cierra en una sola llamada:

<?php

// Equivalent of the basic example above, in one line:
file_put_contents('myfile.txt', 'Hello, world!');

Prefiere fwrite() cuando necesites mantener el archivo abierto durante muchas escrituras (bucles, transmisión, registro), pasar opciones como el bloqueo, o escribir de forma incremental sin reconstruir la cadena completa en memoria.

Errores Comunes

• 'w' trunca inmediatamente — en el momento en que fopen($f, 'w') tiene éxito, el contenido antiguo desaparece, incluso si nunca llamas a fwrite().
• Sin saltos de línea automáticos — debes añadir \n / PHP_EOL tú mismo.
• Olvidar fclose() — los datos pueden quedarse en un búfer y nunca llegar al disco hasta que se cierre el manejador (o termine el script).
• Las comillas simples no expanden escapes — 'Line\n' escribe una barra invertida literal seguida de n. Usa "Line\n" para un salto de línea real.
• El límite de length está en bytes — con texto UTF-8 multibyte, un límite en bytes puede cortar un carácter por la mitad.

Conclusión

fwrite() es la función principal de PHP para escribir cadenas en un archivo abierto. Domina el ciclo de tres pasos abrir–escribir–cerrar, elige el modo correcto de fopen() ('w' para reemplazar, 'a' para añadir), agrega tus propios saltos de línea y verifica el valor de retorno, y podrás escribir desde simples archivos de texto hasta registros de aplicación duraderos.

Funciones Relacionadas

• fopen() — abrir el archivo antes de escribir
• fclose() — vaciar y cerrar el manejador después
• fread() y fgets() — leer los datos de vuelta
• file_put_contents() — escribir un archivo completo en una sola llamada
• feof() — detectar el final de un archivo mientras se lee

Práctica