is_file()

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

is_file() es una función integrada de PHP que indica si una ruta apunta a un archivo regular — un archivo ordinario en el disco, a diferencia de un directorio, el tipo de destino de un enlace simbólico, o un archivo especial (un pipe, socket o nodo de dispositivo). Devuelve true únicamente para archivos regulares y false para todo lo demás, incluidas las rutas que no existen.

Esta es la función a la que se recurre antes de intentar leer, incluir o procesar un archivo, cuando importa más "¿esta ruta apunta realmente a un archivo con el que puedo trabajar?" que "¿existe esta ruta?".

Sintaxis

is_file(string $filename): bool

• $filename — la ruta a verificar. Puede ser relativa (resuelta respecto al directorio de trabajo actual) o absoluta.
• Valor de retorno — true si $filename existe y es un archivo regular, false en caso contrario. No se genera ninguna advertencia cuando el archivo no existe; simplemente se obtiene false.

Ejemplo básico

Usar __FILE__ (la ruta absoluta del script actual) garantiza que la verificación sea exitosa, por lo que el script imprime un mensaje confirmando que la ruta es un archivo regular. Sustituye cualquier ruta que desees: una ruta inexistente o un directorio devuelve false.

is_file() vs file_exists() vs is_dir()

Estas tres funciones se superponen, y elegir la incorrecta es una fuente común de errores:

La trampa principal: file_exists('/some/folder') es true para un directorio. Si luego intentas usar fopen() o include como si fuera un archivo, obtendrás un error. Usa is_file() siempre que el paso siguiente asuma un archivo real:

<?php

$path = sys_get_temp_dir(); // a directory that definitely exists

var_dump(file_exists($path)); // bool(true)  — it exists
var_dump(is_file($path));     // bool(false) — but it is NOT a file
var_dump(is_dir($path));      // bool(true)  — it is a directory

Proteger una lectura de archivo

Un uso típico en el mundo real: confirmar que la ruta es un archivo utilizable antes de leerlo. Combinar is_file() con is_readable() evita tanto los fallos de "no es un archivo" como los de "sin permiso":

<?php

$path = __FILE__;

if (is_file($path) && is_readable($path)) {
    echo "Safe to read: " . basename($path);
} else {
    echo "Cannot read that path.";
}

Esto imprime una salida del estilo Safe to read: is-file.mdx (el basename del script en ejecución), y finaliza de forma limpia si la ruta es un directorio, no existe o no es legible.

La trampa de la caché de stat

PHP almacena en caché los resultados de las comprobaciones del sistema de archivos como is_file() durante la duración de una solicitud para evitar acceder al disco repetidamente. Si un archivo se crea o elimina después de que PHP ya haya verificado la misma ruta, una segunda llamada a is_file() puede devolver la respuesta obsoleta almacenada en caché. Cuando necesites un resultado actualizado — por ejemplo, en un script de larga ejecución que crea un archivo y lo vuelve a verificar inmediatamente — limpia primero la caché:

<?php

clearstatcache();          // discard cached stat results
var_dump(is_file($path));  // now reflects the current state on disk

Problemas comunes

• No es una verificación de seguridad. Una ruta puede pasar is_file() y aun así ser no legible o no escribible. Combínala con is_readable() o is_writable() antes de actuar.
• Se siguen los enlaces simbólicos. is_file() verifica el destino de un symlink, no el enlace en sí. Un symlink que apunta a un archivo regular devuelve true.
• No hay advertencia para rutas inexistentes. A diferencia de abrir un archivo, una ruta inexistente simplemente devuelve false, por lo que is_file() es seguro de llamar sin suprimir errores.

Conclusión

is_file() responde una pregunta precisa — "¿es esto un archivo regular?" — y es la comprobación adecuada que debe colocarse antes de cualquier código que lea, incluya o procese un archivo. Recurre a file_exists() cuando un directorio también sería aceptable, a is_dir() cuando específicamente deseas una carpeta, y combina is_file() con las verificaciones de legibilidad anteriores cuando los permisos importan.

Práctica