stat()

Introdução

A função stat() retorna um único array contendo metadados de baixo nível sobre um arquivo: seu tamanho, permissões, proprietário, inode, contagem de links e três timestamps (acesso, modificação e alteração de inode). É o wrapper PHP em torno da chamada de sistema C stat(), fornecendo em uma única chamada as mesmas informações que você obteria de várias funções separadas, como filesize(), filemtime() e fileperms().

Este artigo aborda a sintaxe, o significado completo de cada valor retornado por stat(), as armadilhas que enganam as pessoas (o cache de stat, links simbólicos e índices string vs. numérico) e exemplos executáveis.

Sintaxe

stat(string $filename): array|false

• $filename — o caminho para o arquivo sobre o qual você deseja informações.
• Valor de retorno — um array descrevendo o arquivo, ou false em caso de falha (por exemplo, o arquivo não existe ou não é legível). Como pode retornar false, sempre verifique o resultado antes de indexá-lo.

stat() segue links simbólicos e reporta sobre o arquivo alvo. Se você precisar de metadados sobre o próprio link, use lstat(). Para obter stat de um arquivo para o qual você já tem um identificador aberto, use fstat().

O que stat() Retorna

O array retornado é incomum: cada valor aparece duas vezes — uma vez sob um índice numérico e outra sob uma chave string descritiva. Assim, $info[7] e $info['size'] têm o mesmo valor. Essa indexação dupla existe por compatibilidade retroativa; prefira as chaves nomeadas para código mais legível.

Algumas observações:

• mode agrupa tanto o tipo de arquivo quanto os bits de permissão. Para obter apenas os bits de permissão Unix (como 0644), use máscara com & 0777; para exibi-los em octal, envolva com decoct().
• ctime é o horário de alteração de inode (quando permissões, propriedade ou links foram alterados pela última vez) — não é o horário de criação do arquivo. A maioria dos sistemas de arquivos Unix não armazena o horário de criação.
• Os valores rdev, blksize e blocks não têm significado no Windows.

Exemplo: Lendo os Metadados de um Arquivo

Este exemplo cria um arquivo temporário, executa stat nele e imprime o tamanho, as permissões e o horário de modificação:

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

echo "Size: {$info['size']} bytes\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";

unlink($path); // clean up

Saída (a permissão e o horário exatos dependem do seu sistema):

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Sempre proteja contra false: passar um caminho inexistente produz um aviso e false, e indexar false lançaria uma exceção.

Armadilha: o Cache de Stat

Por questões de desempenho, o PHP armazena em cache os resultados de stat() e das funções de arquivo relacionadas. Se um arquivo mudar durante a mesma execução do script e você executar stat novamente, poderá obter dados desatualizados. Limpe o cache com clearstatcache() antes de reler:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() vs. as Funções de Propósito Único

Se você precisar de apenas uma informação, as funções dedicadas são mais claras e ligeiramente mais baratas:

• Tamanho do arquivo → filesize()
• Horário de modificação → filemtime()
• Último horário de acesso → fileatime()
• Permissões → fileperms()
• Tipo de arquivo → filetype()

Use stat() quando precisar de vários desses valores ao mesmo tempo, pois ele faz uma única chamada de sistema em vez de várias. Antes de executar stat, você também pode confirmar que o caminho é um arquivo real com is_file() ou file_exists().

Conclusão

A função stat() fornece um snapshot completo e de baixo nível dos metadados de um arquivo em uma única chamada. Lembre-se de verificar o retorno false, use as chaves de array nomeadas para legibilidade, aplique máscara em mode com & 0777 para permissões e limpe o cache de stat se você reler um arquivo que mudou durante a execução do script. Quando precisar de apenas um atributo, prefira a função de propósito único correspondente.

Prática