unlink()

Introducción

La función unlink() de PHP elimina un único archivo del sistema de archivos. El nombre proviene de la llamada al sistema Unix unlink, que elimina un nombre (un "enlace") que apunta a los datos de un archivo. Cuando se elimina el último enlace a un archivo, el archivo en sí queda liberado.

Este capítulo cubre la sintaxis, el valor de retorno, las reglas de permisos y — igual de importante — los errores comunes: advertencias silenciadas, eliminar solo cuando el archivo existe y por qué unlink() no puede eliminar directorios.

Sintaxis

unlink(string $filename, ?resource $context = null): bool

Parámetros

• $filename — la ruta al archivo que se desea eliminar. Puede ser relativa al directorio de trabajo actual o una ruta absoluta.
• $context (opcional) — un recurso de contexto de flujo, utilizado en casos avanzados como eliminar a través de un contenedor de flujo (por ejemplo, FTP). Raramente lo necesitarás.

Valor de retorno

• true si el archivo se eliminó correctamente.
• false si falló — por ejemplo, el archivo no existe, la ruta apunta a un directorio o el proceso no tiene permisos. En caso de fallo, PHP también emite un E_WARNING.

unlink() es la contraparte de las funciones que crean archivos, como fopen() y file_put_contents().

Un ejemplo básico

Comprueba siempre el valor de retorno para que tu script sepa si la eliminación realmente ocurrió:

<?php
// Create a file so we have something to delete.
file_put_contents('example.txt', 'temporary data');

if (unlink('example.txt')) {
    echo "File deleted successfully.";
} else {
    echo "Failed to delete the file.";
}

Salida:

File deleted successfully.

Eliminar solo si el archivo existe

Llamar a unlink() sobre un archivo inexistente devuelve false y genera una advertencia. Protege la llamada con file_exists() (o is_file()) para evitar advertencias innecesarias:

<?php
$path = 'cache/report.tmp';

if (file_exists($path)) {
    unlink($path);
    echo "Removed: {$path}";
} else {
    echo "Nothing to remove.";
}

Si cache/report.tmp no existe, esto imprime Nothing to remove. en lugar de generar una advertencia.

Gestionar fallos de forma limpia

En producción, a menudo querrás reaccionar ante una eliminación fallida en lugar de que el script falle. El operador @ suprime la advertencia, pero un enfoque más limpio es verificar el resultado e informarlo tú mismo:

<?php
$path = 'logs/old.log';

if (!@unlink($path)) {
    // file_exists() distinguishes "already gone" from a real permission error.
    if (file_exists($path)) {
        echo "Could not delete {$path} — check permissions.";
    } else {
        echo "File was already gone.";
    }
}

Permisos: quién puede eliminar un archivo

Una sorpresa habitual: el permiso para eliminar un archivo está controlado por el directorio, no por el archivo. Para eliminar un archivo, el proceso PHP (por ejemplo, el usuario del servidor web como www-data) necesita permiso de escritura y ejecución en el directorio que lo contiene — incluso si el archivo en sí es de solo lectura. Si obtienes errores de "permiso denegado", inspecciona los permisos del directorio padre, no solo los del archivo.

Eliminar múltiples archivos

unlink() elimina un archivo a la vez. Para eliminar varios archivos que coincidan con un patrón, combínalo con glob():

<?php
// Delete every .tmp file in the cache directory.
foreach (glob('cache/*.tmp') as $file) {
    unlink($file);
}

glob() devuelve un array de rutas coincidentes (o un array vacío si ninguna coincide), por lo que el bucle simplemente no hace nada cuando no hay nada que eliminar.

unlink() vs rmdir()

unlink() solo funciona con archivos. Si le pasas un directorio, falla y genera una advertencia. Para eliminar un directorio, usa rmdir() — y ten en cuenta que rmdir() solo funciona con directorios vacíos. Eliminar un directorio no vacío implica eliminar primero su contenido (con unlink() para archivos y rmdir() para subdirectorios) y luego eliminar el directorio en sí.

Errores comunes

• El archivo debe existir. Un archivo inexistente devuelve false y genera una advertencia. Comprueba con file_exists() primero.
• Es permanente. unlink() no mueve el archivo a una papelera de reciclaje; los datos desaparecen inmediatamente.
• No funciona con directorios. Usa rmdir() para directorios.
• Caché de estadísticas. Tras eliminar un archivo, PHP puede seguir informando que existe debido a la caché de estadísticas. Llama a clearstatcache() si vuelves a comprobar la misma ruta en un bucle cerrado.
• Identificadores de archivo abiertos. En Windows no puedes eliminar un archivo que sigue abierto; ciérralo primero con fclose(). En Unix la eliminación está permitida, pero los datos permanecen hasta que se cierre el último identificador.

Conclusión

unlink() es la forma directa de PHP para eliminar un único archivo, devolviendo true en caso de éxito y false (más una advertencia) en caso de fallo. Las prácticas clave son: comprobar si el archivo existe antes de eliminarlo, inspeccionar siempre el valor de retorno, recordar que el permiso de eliminación depende del directorio, y usar rmdir() cuando necesites eliminar directorios. Para una visión más amplia de la lectura, escritura y gestión de archivos, consulta PHP File Handling.

Práctica