filesize()

O que é a Função filesize()?

filesize() é uma função nativa do PHP que retorna o tamanho de um arquivo, medido em bytes, como um inteiro. É a forma padrão de descobrir quanto espaço em disco um arquivo ocupa antes de baixá-lo, exibi-lo, validar um upload ou decidir se deve carregá-lo na memória.

Esta página aborda a sintaxe, o que o valor de retorno significa, a importante armadilha em torno de resultados em cache, como converter bytes brutos em uma string legível por humanos e como lidar com arquivos ausentes ou ilegíveis de forma segura.

Sintaxe

filesize(string $filename): int|false

• $filename — Caminho para o arquivo. Pode ser um caminho relativo, um caminho absoluto ou um wrapper de URL (por exemplo, http://, ftp://) onde o protocolo suporta informar o tamanho.
• Valor de retorno — O tamanho do arquivo em bytes como um inteiro, ou false em caso de falha (por exemplo, o arquivo não existe ou você não tem permissão para acessá-lo).

Como o tamanho está em bytes, um arquivo reportado como 2048 tem 2 KB, e 1048576 é exatamente 1 MB.

Um Exemplo Básico

O exemplo abaixo cria um pequeno arquivo temporário, escreve uma string conhecida nele e informa seu tamanho. Escrever o arquivo primeiro significa que o exemplo é totalmente autossuficiente e executável:

<?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.

A string Hello, world! tem 13 caracteres ASCII, portanto o arquivo tem exatamente 13 bytes. Para arquivos de texto em codificação de byte único, a contagem de bytes é igual à contagem de caracteres; caracteres multibyte (UTF-8) contam como mais de um byte.

filesize() opera no arquivo como está no disco. Ela não conta bytes na memória e, para links simbólicos, reporta o tamanho do arquivo de destino.

Tratando um Arquivo Ausente ou Ilegível

Se o arquivo não existir, filesize() retorna false e emite um aviso. Sempre verifique se o arquivo existe primeiro para poder falhar graciosamente:

<?php

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

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

Como false é vagamente igual a 0, nunca escreva if (filesize($f) == 0) para testar um arquivo vazio sem primeiro confirmar que o arquivo existe — um arquivo ausente e um arquivo vazio pareceriam idênticos. Consulte file_exists() para o pré-verificação segura.

A Armadilha do Cache (clearstatcache)

O PHP armazena em cache o resultado de funções do sistema de arquivos como filesize(), filemtime() e stat() por questões de desempenho. Se um arquivo mudar durante a mesma execução do script, filesize() pode retornar o tamanho antigo. Chame clearstatcache() para forçar uma leitura atualizada:

<?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

Sem a chamada clearstatcache(), o segundo echo ainda poderia imprimir 5. Esta é a fonte mais comum de resultados "errados" do filesize().

Convertendo Bytes em um Tamanho Legível

Contagens brutas de bytes são difíceis de ler. Um pequeno auxiliar converte-os para KB, MB, GB e assim por diante:

<?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

Aqui number_format() cuida das casas decimais e 1024 ** $factor divide pela potência correta de 1024. Substitua por round() se preferir um resultado numérico sem separadores de milhares.

Quando Devo Usar filesize()?

• Validando uploads — rejeite arquivos maiores que um limite antes de salvá-los (combine com is_uploaded_file()).
• Definindo cabeçalhos de download — envie um cabeçalho Content-Length correto para que os navegadores possam exibir uma barra de progresso.
• Decidindo como ler um arquivo — para um arquivo enorme, transmita-o com fopen()/fread() em vez de carregá-lo todo com file_get_contents().
• Monitoramento — acompanhe se um arquivo de log está crescendo conforme esperado.

Funções Relacionadas

• file_exists() — verifica se um arquivo existe antes de medi-lo.
• filemtime() — obtém o tempo da última modificação de um arquivo.
• filetype() — determina se um caminho é um arquivo, diretório ou link.
• file_get_contents() — lê um arquivo inteiro em uma string.

Resumo

filesize() retorna o tamanho de um arquivo em bytes, ou false em caso de falha. Sempre confirme que o arquivo existe primeiro, lembre-se de chamar clearstatcache() quando um arquivo muda durante a execução do script e converta bytes em uma unidade amigável com um auxiliar ao exibir o resultado para os usuários.

Prática