lstat()

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

lstat() coleta estatísticas (tamanho, timestamps, proprietário, permissões e mais) sobre um arquivo indicado por $filename. O "l" significa link: ao contrário de stat(), que segue um link simbólico e reporta sobre o destino para o qual ele aponta, lstat() reporta sobre o próprio link.

Essa distinção só importa para links simbólicos. Quando $filename é um arquivo comum, lstat() e stat() retornam dados idênticos.

Esta página abrange a sintaxe, o array que ela retorna, um exemplo executável que a contrasta com stat(), e as armadilhas comuns a observar.

Sintaxe

lstat(string $filename): array|false

• $filename — caminho para o arquivo ou link simbólico a inspecionar.
• Retorna um array associativo de estatísticas em caso de sucesso, ou false em caso de falha (por exemplo, se o caminho não existir).

Um Exemplo Executável

O script abaixo cria um arquivo real e um link simbólico que aponta para ele, depois inspeciona ambos com lstat() e stat() para que você possa ver a diferença:

<?php

$target = sys_get_temp_dir() . '/lstat_target.txt';
$link   = sys_get_temp_dir() . '/lstat_link';

file_put_contents($target, 'hello');   // 5-byte target file
@unlink($link);
symlink($target, $link);

$linkInfo   = lstat($link);   // the link itself
$targetInfo = stat($link);    // follows the link to the target

echo "Link size (lstat):  {$linkInfo['size']} bytes\n";
echo "Target size (stat): {$targetInfo['size']} bytes\n";
echo "Link modified:      " . date('Y-m-d', $linkInfo['mtime']) . "\n";

unlink($link);
unlink($target);

Saída típica:

Link size (lstat):  65 bytes
Target size (stat): 5 bytes
Link modified:      2026-06-20

O tamanho retornado por lstat() é o comprimento dos dados do caminho do link simbólico, não o tamanho do arquivo para o qual ele aponta — essa é exatamente a informação que stat() ocultaria de você.

O Array Retornado

lstat() retorna a mesma estrutura que stat(): um array de 26 elementos onde cada valor aparece duas vezes — uma vez sob um índice numérico e uma vez sob uma chave string legível. Prefira sempre as chaves nomeadas para maior clareza:

Como as chaves nomeadas e numéricas contêm os mesmos valores, $info['size'] e $info[7] são intercambiáveis — mas a forma nomeada é muito mais fácil de ler.

Quando Usar lstat() vs stat()

• Use stat() quando você se importa com o conteúdo do arquivo e quer que os links sejam resolvidos de forma transparente.
• Use lstat() quando estiver auditando o próprio sistema de arquivos — por exemplo, distinguindo arquivos reais de links simbólicos, ou detectando um link pendente cujo destino foi deletado.

Para verificar se um caminho é um link simbólico antes de chamar lstat(), combine-o com is_link(). Para ler para onde um link aponta, use readlink(), e para criar um, use symlink().

Armadilhas

• Cache de stat obsoleto. O PHP armazena em cache os resultados de stat/lstat por requisição. Se um arquivo mudar durante a execução, chame clearstatcache(true, $filename) antes de relê-lo.
• Windows. Links simbólicos existem no Windows, mas exigem privilégios elevados para criar; o comportamento pode diferir de sistemas POSIX.
• Permissões. Seu processo PHP precisa de acesso de leitura ao diretório que contém o link. Em sistemas reforçados, módulos de segurança (como SELinux ou restrições de open_basedir) podem bloquear o acesso mesmo quando as permissões de arquivo parecem corretas.

Conclusão

lstat() fornece os metadados de um link simbólico sem segui-lo — o único recurso que stat() não consegue fazer. Recorra a ela sempre que precisar inspecionar os próprios links em vez de seus destinos, leia os valores pelas suas chaves nomeadas e sempre verifique se há retorno false antes de confiar no resultado.

Prática