filemtime()

A função filemtime() é uma função PHP nativa que retorna o momento em que o conteúdo de um arquivo foi modificado pela última vez, como um timestamp Unix. É uma das funções de inspeção do sistema de arquivos do PHP e é comumente utilizada para invalidação de cache, rótulos de "última atualização" e para detectar se um arquivo foi alterado desde a última leitura.

Este capítulo aborda a sintaxe, o valor de retorno, a diferença entre filemtime() e as funções relacionadas filectime() / fileatime(), a formatação do resultado para leitura humana, o tratamento de erros e a armadilha do cache de resultados que pega quase todo mundo de surpresa.

Sintaxe

filemtime(string $filename): int|false

• $filename — caminho para o arquivo (ou diretório) a ser inspecionado.
• Valor de retorno — o tempo de modificação como um timestamp Unix (segundos desde 1º de janeiro de 1970 UTC) em caso de sucesso, ou false em caso de falha.

O "tempo de modificação" (mtime) muda sempre que o conteúdo do arquivo é gravado. Ele não muda quando o arquivo é apenas lido, nem quando somente seus metadados (permissões, proprietário) são alterados — isso é o tempo de alteração do inode, informado por filectime().

Um exemplo básico

Como um timestamp Unix é apenas um número inteiro grande, você normalmente o passa para date() para produzir uma string legível:

<?php

$filename = __FILE__; // inspect this script itself

$timestamp = filemtime($filename);
$readable  = date('F d Y H:i:s', $timestamp);

echo "The file was last modified on $readable";

__FILE__ é uma constante mágica que sempre aponta para o script atual, portanto este trecho é executado sem que você precise criar um arquivo separado. filemtime() retorna o timestamp e date() o formata (aqui: nome completo do mês, dia, ano e hora no formato 24h).

Sempre trate os erros

filemtime() retorna false quando o arquivo não existe ou não pode ser lido, e também emite um aviso. Como false é livremente igual a 0, nunca passe o resultado bruto diretamente para date() — verifique-o primeiro, de preferência após confirmar a existência do arquivo com file_exists():

<?php

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

if (!file_exists($filename)) {
    echo "File not found.";
} else {
    $timestamp = filemtime($filename);

    if ($timestamp === false) {
        echo "Could not read the modification time.";
    } else {
        echo "Last modified: " . date('Y-m-d H:i:s', $timestamp);
    }
}

Use a comparação estrita === false: um timestamp legítimo nunca é false, mas == false também capturaria o timestamp (impossível na prática) 0.

mtime vs. ctime vs. atime

PHP expõe três timestamps de arquivo diferentes. Saber qual usar evita bugs sutis:

Para "mostrar quando foi editado pela última vez", quase sempre você vai querer filemtime().

A armadilha do cache: clearstatcache()

PHP armazena em cache os resultados de funções do sistema de arquivos como filemtime() durante a duração de uma requisição. Se você modificar um arquivo e chamar filemtime() novamente no mesmo script, poderá obter o valor desatualizado. Chame clearstatcache() para forçar uma nova consulta:

<?php

$filename = tempnam(sys_get_temp_dir(), 'demo');

file_put_contents($filename, 'first write');
$first = filemtime($filename);

sleep(1);
touch($filename);          // bump the mtime

clearstatcache();          // without this, you may still see $first
$second = filemtime($filename);

echo $second > $first ? "mtime updated\n" : "mtime unchanged (cached)\n";

unlink($filename);

Aqui touch() atualiza o tempo de modificação, e clearstatcache() garante que o segundo filemtime() reflita essa atualização.

Um uso prático: cache busting

Um uso comum no mundo real é adicionar o mtime do arquivo à URL de um recurso para que os navegadores façam o download novamente somente quando o arquivo for realmente alterado:

<?php

$cssPath = __FILE__; // pretend this is 'styles.css'
$version = filemtime($cssPath);

echo "/assets/styles.css?v=$version";

Cada vez que o CSS é editado, $version muda, invalidando o cache do navegador automaticamente.

Conclusão

filemtime() informa quando o conteúdo de um arquivo foi modificado pela última vez, como um timestamp Unix, e retorna false em caso de falha. Combine-a com date() para formatar o resultado, proteja-se contra false, lembre-se de usar clearstatcache() ao reler um arquivo que você acabou de alterar, e recorra a filectime() ou fileatime() quando precisar do tempo de alteração ou de acesso. Para um conjunto completo de estatísticas de arquivo em uma única chamada, consulte stat().

Prática