Introducción a la creación y manipulación de archivos en PHP

PHP se ejecuta en el servidor, por lo que puede leer y escribir archivos reales en disco: informes generados, HTML en caché, entradas de registro, CSV exportados, contenido subido por usuarios y configuración. Este capítulo cubre el flujo de trabajo principal para crear y escribir archivos: abrir un manejador de archivo con el modo correcto, escribir datos y cerrar el manejador. También explica cuándo conviene usar los helpers de una sola línea más simples.

Hay dos familias de herramientas para escritura de archivos en PHP:

• Manejadores de flujo — fopen() / fwrite() / fclose(). Lo mejor cuando se escribe de forma incremental (añadiendo líneas de registro, transmitiendo salida grande) y se quiere control preciso sobre el modo del archivo.
• Helpers de una sola llamada — file_put_contents(). Lo mejor cuando se tiene la cadena completa en memoria y solo se quiere volcarla a un archivo en una sola llamada.

Usaremos primero el enfoque con flujos porque entender los modos es la clave para todo lo demás.

Crear y escribir un archivo con fopen()

Para escribir en un archivo primero se abre con fopen(). Recibe la ruta del archivo y una cadena de modo, y devuelve un manejador de archivo (un recurso) sobre el que operan las demás funciones:

<?php
$file = fopen("example.txt", "w");   // open for writing, truncating the file
fwrite($file, "This is an example.\n");
fclose($file);                       // always close the handle

Lo que hace cada línea:

• fopen("example.txt", "w") abre example.txt en modo escritura. Si el archivo no existe se crea; si ya existe su contenido se borra (se trunca a longitud cero).
• fwrite() escribe la cadena en el archivo y devuelve el número de bytes escritos (o false en caso de fallo).
• fclose() vacía los datos en búfer y libera el manejador. Omitirlo puede dejar datos sin escribir hasta que finalice el script.

Una ruta relativa como "example.txt" se resuelve respecto al directorio de trabajo actual del script. Para mayor seguridad y previsibilidad, prefiera una ruta absoluta, p. ej. __DIR__ . "/example.txt".

Modos de archivo

El modo que se pasa a fopen() determina si el archivo se crea, trunca o añade, y si puede leerse. Estos son los modos relevantes para crear y escribir:

Use "x" cuando no deba sobreescribir un archivo existente — por ejemplo, al escribir un archivo de bloqueo. Use "a" para registros, donde cada ejecución debe añadir al archivo en lugar de borrarlo.

Añadir en lugar de sobreescribir

Un error muy común es usar "w" para un registro y preguntarse por qué el archivo solo tiene una línea. Abra con "a" para conservar el contenido previo y añadir al final:

<?php
$log = fopen("app.log", "a");        // append mode — never erases
fwrite($log, "[" . date("Y-m-d H:i:s") . "] User logged in\n");
fclose($log);

Ejecute esto dos veces y el archivo tendrá dos líneas con marca de tiempo en lugar de una.

El atajo: file_put_contents()

Cuando ya se tiene el contenido completo como cadena, file_put_contents() realiza apertura, escritura y cierre en una sola llamada:

<?php
// Overwrite (or create) the file with this exact content:
file_put_contents("greeting.txt", "Hello, world!\n");

// Append instead of overwriting:
file_put_contents("app.log", "another line\n", FILE_APPEND);

Devuelve el número de bytes escritos, o false en caso de fallo. Es la opción más limpia para cargas pequeñas en memoria. Recurra a fopen()/fwrite() cuando escriba en un bucle o necesite mantener el manejador abierto a través de varias operaciones.

Leer lo que se escribió

Para confirmar una escritura, abra el archivo en modo lectura ("r") y léalo. El capítulo complementario PHP Abrir/Leer archivos lo cubre en profundidad, pero la versión con flujos es:

<?php
$file = fopen("example.txt", "r");
$contents = fread($file, filesize("example.txt"));
fclose($file);
echo $contents;

Aquí fread() lee hasta filesize("example.txt") bytes — el archivo completo — en $contents. Para una sola línea, file_get_contents() lee el archivo entero en una cadena sin manejador que gestionar.

Manejar errores y archivos inexistentes

fopen() devuelve false (y emite una advertencia) si no puede abrir el archivo — permisos incorrectos, un directorio inexistente o un disco de solo lectura. Compruebe siempre antes de escribir:

<?php
$file = fopen("/no/such/dir/example.txt", "w");
if ($file === false) {
    echo "Could not open the file for writing.";
} else {
    fwrite($file, "ok");
    fclose($file);
}

Antes de leer un archivo que no creó en la misma ejecución, confirme que existe con file_exists() para evitar advertencias de filesize() o fread().

Otras funciones de archivo útiles

Más allá de crear y escribir, PHP incluye un conjunto completo de herramientas para la gestión de archivos:

• file_get_contents() — leer un archivo completo en una cadena en una sola llamada.
• file_put_contents() — escribir una cadena en un archivo en una sola llamada.
• file_exists() — comprobar si una ruta existe antes de actuar sobre ella.
• unlink() — eliminar un archivo.
• rename() — renombrar o mover un archivo.
• copy() — copiar un archivo a una nueva ruta.

Para archivos subidos desde un formulario, consulte PHP Subida de archivos, y para una visión general de la API del sistema de archivos, consulte PHP Manejo de archivos.

Resumen

• Abra un archivo con fopen($path, $mode); el modo controla el comportamiento de creación/truncado/añadido.
• Use "w" para sobreescribir, "a" para añadir y "x" para rechazar sobreescribir un archivo existente.
• fwrite() escribe y fclose() vacía y libera el manejador — cierre siempre.
• Para escrituras de cadena completa, file_put_contents() es la alternativa concisa de una sola llamada.
• Compruebe el valor de retorno de fopen() y use file_exists() para escribir código robusto sin advertencias.

Práctica