filesize()

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

filesize() es una función integrada de PHP que devuelve el tamaño de un archivo, medido en bytes, como un entero. Es la forma estándar de averiguar cuánto espacio en disco ocupa un archivo antes de descargarlo, mostrarlo, validar una carga o decidir si leerlo en memoria.

Esta página cubre la sintaxis, el significado del valor de retorno, el importante problema con los resultados en caché, cómo convertir bytes en una cadena legible para humanos y cómo manejar con seguridad archivos faltantes o ilegibles.

Sintaxis

filesize(string $filename): int|false

• $filename — Ruta al archivo. Puede ser una ruta relativa, una ruta absoluta o un envoltorio de URL (por ejemplo, http://, ftp://) donde el protocolo admita informar un tamaño.
• Valor de retorno — El tamaño del archivo en bytes como entero, o false en caso de error (por ejemplo, el archivo no existe o no tienes permiso para acceder a él).

Dado que el tamaño está en bytes, un archivo reportado como 2048 equivale a 2 KB, y 1048576 es exactamente 1 MB.

Un ejemplo básico

El siguiente ejemplo crea un pequeño archivo temporal, escribe una cadena conocida en él y muestra su tamaño. Escribir el archivo primero significa que el ejemplo es completamente autocontenido y ejecutable:

<?php

$filename = 'example.txt';
file_put_contents($filename, 'Hello, world!'); // 13 bytes

$bytes = filesize($filename);
echo "The file '$filename' is $bytes bytes.";
// The file 'example.txt' is 13 bytes.

La cadena Hello, world! tiene 13 caracteres ASCII, por lo que el archivo tiene exactamente 13 bytes. Para archivos de texto en una codificación de un solo byte, el número de bytes equivale al número de caracteres; los caracteres multibyte (UTF-8) cuentan como más de un byte.

filesize() actúa sobre el archivo tal como está en el disco. No cuenta bytes en memoria, y para enlaces simbólicos informa el tamaño del archivo destino.

Manejo de un archivo faltante o ilegible

Si el archivo no existe, filesize() devuelve false y emite una advertencia. Verifica siempre que el archivo exista antes para poder fallar de forma controlada:

<?php

$filename = 'does-not-exist.txt';

if (file_exists($filename)) {
    echo filesize($filename) . " bytes";
} else {
    echo "File not found.";
}
// File not found.

Dado que false es equivalente de forma laxa a 0, nunca escribas if (filesize($f) == 0) para comprobar si un archivo está vacío sin confirmar antes que existe — un archivo faltante y uno vacío parecerían idénticos. Consulta file_exists() para la verificación previa segura.

El problema con la caché (clearstatcache)

PHP guarda en caché el resultado de funciones del sistema de archivos como filesize(), filemtime() y stat() por motivos de rendimiento. Si un archivo cambia durante la misma ejecución del script, filesize() puede devolver el tamaño antiguo. Llama a clearstatcache() para forzar una lectura actualizada:

<?php

$filename = 'log.txt';
file_put_contents($filename, 'first');
echo filesize($filename) . "\n"; // 5

file_put_contents($filename, 'first-second');
clearstatcache(); // discard the cached size
echo filesize($filename) . "\n"; // 12

Sin la llamada a clearstatcache(), el segundo echo podría seguir imprimiendo 5. Esta es la fuente más común de resultados "incorrectos" de filesize().

Conversión de bytes a un tamaño legible

Los recuentos de bytes en bruto son difíciles de leer. Un pequeño ayudante los convierte a KB, MB, GB, etc.:

<?php

function humanFilesize(int $bytes, int $decimals = 2): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $factor = (int) floor((strlen((string) $bytes) - 1) / 3);
    $value = $bytes / (1024 ** $factor);

    return number_format($value, $decimals) . ' ' . $units[$factor];
}

echo humanFilesize(13);        // 13.00 B
echo "\n";
echo humanFilesize(2048);      // 2.00 KB
echo "\n";
echo humanFilesize(1048576);   // 1.00 MB

Aquí number_format() gestiona los decimales y 1024 ** $factor divide entre la potencia correcta de 1024. Usa round() si prefieres un resultado numérico sin separadores de miles.

¿Cuándo usaría filesize()?

• Validar cargas — rechaza archivos más grandes que un límite antes de guardarlos (combínalo con is_uploaded_file()).
• Establecer cabeceras de descarga — envía una cabecera Content-Length correcta para que los navegadores puedan mostrar una barra de progreso.
• Decidir cómo leer un archivo — para un archivo enorme, recórrelo con fopen()/fread() en lugar de cargarlo todo con file_get_contents().
• Monitoreo — comprueba si un archivo de registro está creciendo según lo esperado.

Funciones relacionadas

• file_exists() — comprueba que un archivo existe antes de medirlo.
• filemtime() — obtiene la hora de la última modificación de un archivo.
• filetype() — determina si una ruta es un archivo, directorio o enlace.
• file_get_contents() — lee un archivo completo en una cadena.

Resumen

filesize() devuelve el tamaño de un archivo en bytes, o false en caso de error. Confirma siempre que el archivo existe primero, recuerda llamar a clearstatcache() cuando un archivo cambia durante la ejecución del script, y convierte los bytes a una unidad amigable con un ayudante cuando muestres el resultado a los usuarios.

Práctica