fileatime()

O Que a Função fileatime() Faz

A função fileatime() é uma função nativa do PHP que retorna o último tempo de acesso de um arquivo — o momento em que seu conteúdo foi lido pela última vez. O valor é retornado como um timestamp Unix inteiro (o número de segundos desde 1º de janeiro de 1970, UTC), que normalmente é formatado com date() antes de ser exibido ao usuário.

Esta página abrange a sintaxe, o valor de retorno, um exemplo executável, como o tempo de acesso difere dos tempos de modificação e alteração relacionados, e a armadilha de cache que confunde a maioria das pessoas.

Sintaxe

fileatime(string $filename): int|false

• $filename — o caminho para o arquivo que você deseja inspecionar. Pode ser relativo (resolvido em relação ao diretório de trabalho do script) ou absoluto.
• Valor de retorno — um timestamp Unix inteiro em caso de sucesso, ou false em caso de falha (por exemplo, o arquivo não existe ou você não tem permissão para executar stat nele). Como false é um valor PHP válido, sempre compare com !== false em vez de uma verificação de veracidade solta.

Atenção sobre os tempos de acesso no Linux. Em sistemas Linux modernos, opções de montagem como noatime ou relatime deliberadamente impedem a atualização do tempo de acesso a cada leitura, para economizar gravações em disco. Se fileatime() não mudar após você ler um arquivo, isso é a configuração do sistema de arquivos em ação — não um bug no seu código.

Como Usar fileatime()

1. Chame fileatime(), passando o caminho do arquivo que você deseja verificar.
2. Verifique o resultado contra false antes de usá-lo, para que um arquivo ausente não produza um aviso quando você o passar para date().
3. Formate o timestamp com date() para transformá-lo em uma string legível por humanos.

<?php

// Create a small file so the example is self-contained and runnable.
$filename = 'example.txt';
file_put_contents($filename, "Hello, fileatime!\n");

// Read it back to register an access.
$contents = file_get_contents($filename);

$lastAccess = fileatime($filename);

if ($lastAccess !== false) {
    $when = date('Y-m-d H:i:s', $lastAccess);
    echo "The file {$filename} was last accessed on {$when}.\n";
} else {
    echo "Could not read the access time for {$filename}.\n";
}

unlink($filename); // tidy up

Este script cria example.txt, lê-o e, em seguida, pergunta ao fileatime() quando foi acessado pela última vez. A guarda !== false garante que um arquivo ausente ou ilegível seja tratado de forma adequada em vez de emitir um aviso. A saída tem a seguinte aparência:

The file example.txt was last accessed on 2026-06-21 10:42:07.

fileatime() vs. filemtime() vs. filectime()

O PHP expõe três timestamps intimamente relacionados. Escolher o correto é importante:

Se você quer saber "quando alguém abriu este arquivo pela última vez", use fileatime(). Se você quer saber "quando os dados foram alterados pela última vez" (o caso comum para invalidação de cache), use filemtime().

A Armadilha do Cache

O PHP armazena em cache o resultado das funções de status de arquivo como fileatime(), filemtime() e stat() durante a duração de uma requisição. Se você ler um arquivo novamente e verificar seu tempo de acesso dentro da mesma execução do script, poderá obter um valor desatualizado. Limpe o cache com clearstatcache() antes de reler:

<?php

$filename = 'example.txt';
file_put_contents($filename, "data\n");

$first = fileatime($filename);

clearstatcache();                       // force a fresh stat() next time
$contents = file_get_contents($filename);
clearstatcache();
$second = fileatime($filename);

echo ($second >= $first)
    ? "Access time is fresh.\n"
    : "Access time looks stale.\n";

unlink($filename);

Quando Eu Usaria Isso?

• Auditar quais arquivos foram lidos recentemente (rotação de logs, limpeza por "menos recentemente usado").
• Detectar uploads não utilizados ou arquivos temporários que podem ser excluídos com segurança.
• Diagnosticar se um processo está realmente acessando um arquivo que você espera que ele acesse.

Para lógica baseada em modificação (reconstrução de cache quando os dados de origem mudam), use filemtime() em vez disso. Para verificar se um arquivo existe antes de chamar qualquer uma dessas funções, combine-as com file_exists(). Para o conjunto completo de metadados em uma única chamada, consulte stat().

Resumo

fileatime() retorna o timestamp Unix do último acesso de um arquivo, ou false em caso de falha. Sempre proteja o resultado com !== false, formate-o com date() e lembre-se de duas armadilhas: as montagens Linux podem suprimir as atualizações do tempo de acesso, e o PHP armazena em cache os resultados de stat dentro de uma requisição, a menos que você chame clearstatcache().

Prática