file_put_contents()

La función file_put_contents() escribe una cadena en un archivo en una sola llamada. Es el reemplazo moderno y de una sola línea para la secuencia clásica fopen() → fwrite() → fclose(): PHP abre el archivo, escribe los datos y cierra el manejador por ti. Esta página cubre su sintaxis, parámetros, valor de retorno, indicadores para agregar datos y bloqueo, y los errores que con más frecuencia confunden a los desarrolladores.

Sintaxis

file_put_contents(string $filename, mixed $data, int $flags = 0, ?resource $context = null): int|false

Parámetros

Valor de retorno

file_put_contents() devuelve el número de bytes escritos, o false en caso de error. Dado que 0 es un resultado válido (pero falsy) cuando se escribe una string vacía, verifica siempre el fallo con la comparación estricta === false en lugar de una prueba de veracidad flexible.

Escribir un archivo

Por defecto la función sobreescribe el contenido existente del archivo (o lo crea si no existe):

<?php

$filename = 'myfile.txt';
$data     = 'This is some data to be written to the file.';

$bytes = file_put_contents($filename, $data);

if ($bytes === false) {
    echo "Failed to write to $filename";
} else {
    echo "Wrote $bytes bytes to $filename";
}

Salida:

Wrote 44 bytes to myfile.txt

El contador devuelto, 44, es la longitud de la string en bytes.

Agregar datos en lugar de sobreescribir

Pasa el indicador FILE_APPEND para añadir al final del archivo en lugar de reemplazar su contenido — muy útil para archivos de registro:

<?php

$log = 'app.log';

file_put_contents($log, "First line\n", FILE_APPEND);
file_put_contents($log, "Second line\n", FILE_APPEND);

echo file_get_contents($log);

Salida:

First line
Second line

Sin FILE_APPEND, la segunda llamada borraría la primera línea.

Bloquear el archivo mientras se escribe

Si varios procesos pueden escribir en el mismo archivo al mismo tiempo, agrega LOCK_EX para adquirir un bloqueo exclusivo durante la escritura. Combina los indicadores con el operador OR a nivel de bits (|):

<?php

file_put_contents('counter.txt', "ping\n", FILE_APPEND | LOCK_EX);

Esto evita que dos escritores intercalen su salida y corrompan el archivo.

Escribir un array

Cuando $data es un array, sus elementos de tipo string se concatenan sin separador. Únelos tú mismo si necesitas delimitadores:

<?php

$lines = ['apple', 'banana', 'cherry'];

file_put_contents('fruits.txt', implode("\n", $lines));

echo file_get_contents('fruits.txt');

Salida:

apple
banana
cherry

Errores comunes

• Fallo silencioso por permisos. Si el directorio no tiene permisos de escritura, la llamada devuelve false y emite una advertencia — no lanza una excepción. Verifica el valor de retorno (=== false) o envuelve la llamada e inspecciona error_get_last().
• El directorio padre debe existir. file_put_contents() crea el archivo pero no los directorios faltantes. Llama a mkdir($dir, 0777, true) primero si es necesario.
• FILE_APPEND no es lo mismo que sobreescribir. Olvidar el indicador es la causa más común de "mi registro sigue borrándose."
• Los datos vacíos son válidos. Escribir '' devuelve 0, que es falsy — usa === false para no confundir una escritura vacía exitosa con un error.

Funciones relacionadas

• file_get_contents() — la contraparte de lectura que carga un archivo completo en una string.
• fwrite() — escritura de nivel inferior cuando necesitas un manejador abierto (por ejemplo, muchas escrituras pequeñas en un bucle).
• fopen() — abre un manejador de archivo para lectura o escritura mediante stream.
• file_exists() — verifica si un archivo existe antes de escribir.

Conclusión

file_put_contents() es la forma más sencilla de escribir una string en un archivo en PHP: una sola llamada abre, escribe y cierra el archivo. Usa FILE_APPEND para agregar datos a un archivo, LOCK_EX para escrituras concurrentes, y verifica siempre el éxito con una comprobación estricta === false.

Práctica