file_put_contents en PHP: bytes escritos y anexado

Comprobar el resultado con rigor

file_put_contents devuelve los bytes escritos o false si falla. Cero bytes puede ser una escritura válida de una cadena vacía, de modo que la comprobación debe ser estricta. El ejemplo crea un archivo en el directorio del propio script; pruébalo en una carpeta de ejercicios, no sobre un archivo de configuración.

$ruta = __DIR__.'/salida-ejercicio.txt';
$texto = "Primera línea\n";
$bytes = file_put_contents($ruta, $texto, LOCK_EX);
if ($bytes === false) {
    throw new RuntimeException('No se pudo escribir');
}
echo $bytes, PHP_EOL; // 15, con esta cadena UTF-8

El número indica bytes, no caracteres visibles. En UTF-8 una letra acentuada puede ocupar más de un byte; compara con strlen($texto) si necesitas comprobar que se escribió toda la cadena.

Reemplazar frente a añadir

Sin FILE_APPEND, la escritura reemplaza el contenido del archivo existente. Para añadir un registro al final, combina las banderas con el operador de bits:

$bytes = file_put_contents($ruta, "Otra línea\n", FILE_APPEND | LOCK_EX);
if ($bytes === false) {
    throw new RuntimeException('No se pudo añadir');
}

LOCK_EX coordina escritores que respetan el bloqueo. No convierte una secuencia de leer, calcular y escribir en una transacción. Un contador compartido puede perder incrementos si dos procesos leen el mismo valor antes de escribir.

Rutas y datos sensibles

No construyas la ruta directamente desde un parámetro del visitante. Selecciona nombres permitidos dentro de un directorio conocido, y comprueba que exista y sea escribible por el usuario del proceso. Cambiar permisos de todo el servidor a 777 no es una solución proporcionada.

Si necesitas sustituir un documento completo con garantías adicionales, diseña un proceso con archivo temporal y reemplazo apropiado para el sistema de archivos. Mantén además una copia anterior cuando el archivo sea importante. Los registros de depuración no deben contener contraseñas, tokens o documentos de personas; un archivo que queda bajo el directorio público puede ser descargable.

Referencia 1