filectime()

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

A função filectime() é uma função PHP integrada que retorna o horário de alteração do inode de um arquivo — um timestamp Unix (o número de segundos desde 1º de janeiro de 1970) que representa o momento em que os metadados do arquivo foram alterados pela última vez. "Inode" é a estrutura de dados que um sistema de arquivos semelhante ao Unix usa para armazenar informações sobre um arquivo (suas permissões, proprietário, tamanho e a localização de seus blocos de dados) separadamente do conteúdo real do arquivo.

Um ponto comum de confusão: filectime() não retorna o horário de criação do arquivo. O "c" significa change (alteração), não create (criação). O horário de alteração do inode é atualizado sempre que os metadados do arquivo mudam — por exemplo, quando você executa chmod, chown, renomeia o arquivo, ou até quando edita seu conteúdo (o que também atualiza os metadados). O PHP não possui uma função portável para o horário verdadeiro de criação.

Use a função correta para o que você realmente precisa:

• filectime() — quando o inode (metadados) foi alterado pela última vez (permissões, propriedade, contagem de links, renomeação).
• filemtime() — quando o conteúdo do arquivo foi modificado pela última vez.
• fileatime() — quando o arquivo foi acessado pela última vez (lido).

Aqui está a sintaxe básica da função filectime():

A sintaxe PHP de filectime()

filectime(string $filename): int|false

Onde $filename é o caminho do arquivo a ser verificado. A função retorna o horário de alteração do inode como um timestamp Unix, ou false (com um E_WARNING) se o arquivo não existir ou não puder ser acessado. Como false e um timestamp podem ambos parecer "falsy" em comparações flexíveis (um timestamp nunca é 0 na prática, mas o código defensivo importa), sempre verifique o resultado com o operador estrito !== false.

Como Usar a Função filectime()?

O uso da função filectime() é simples. Aqui estão os passos a seguir:

1. Chame a função filectime(), passando o nome do arquivo que deseja verificar.
2. A função retornará um timestamp Unix representando o horário de alteração do inode, ou false em caso de falha.
3. Você pode formatar o timestamp Unix usando a função date() para exibir o horário em um formato mais legível.

Aqui está um exemplo de código que demonstra como usar a função filectime():

Como Usar a Função filectime()?

<?php

$filename = 'myfile.txt';
$last_change_time = filectime($filename);

if ($last_change_time !== false) {
    $change_time_string = date('F d Y H:i:s', $last_change_time);
    echo "The file $filename had its inode changed on $change_time_string";
} else {
    echo "Could not retrieve inode change time for $filename.";
}

Nota: O parâmetro filename aceita tanto caminhos relativos quanto absolutos. Se você usar um caminho relativo, ele será resolvido em relação ao diretório de trabalho atual.

Neste exemplo, verificamos o horário de alteração do inode de myfile.txt usando a função filectime(). Armazenamos o timestamp Unix retornado na variável $last_change_time. O código primeiro verifica se a função não retornou false, depois formata o timestamp usando date(). Note que date() depende do fuso horário padrão do servidor; use date_default_timezone_set() se precisar de uma saída com fuso horário específico. Por fim, exibimos uma mensagem indicando quando os metadados do arquivo foram alterados pela última vez.

Um Exemplo Autocontido e Executável

O trecho acima depende de um arquivo existente no disco. O exemplo abaixo cria um arquivo temporário, altera suas permissões para forçar uma alteração de inode e, em seguida, lê o timestamp — para que você possa executá-lo como está e ver a saída real:

<?php

// Create a temporary file
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, 'hello');

// Changing permissions updates the inode change time (ctime)
chmod($path, 0644);

$ctime = filectime($path);
echo "ctime: " . date('Y-m-d H:i:s', $ctime) . PHP_EOL;
echo "Is it a Unix timestamp (integer)? " . (is_int($ctime) ? 'yes' : 'no') . PHP_EOL;

unlink($path); // clean up

Isso imprime o horário de alteração formatado seguido de Is it a Unix timestamp (integer)? yes, confirmando que filectime() retorna um timestamp inteiro.

Atenção ao Cache de Stat

O PHP armazena em cache o resultado das funções de stat do sistema de arquivos como filectime(), filemtime() e fileperms() durante a duração de uma única requisição para melhorar o desempenho. Se você alterar um arquivo e imediatamente chamar filectime() nele novamente no mesmo script, pode obter o valor obsoleto, em cache. Chame clearstatcache() primeiro para obter uma leitura atualizada:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
$first = filectime($path);

sleep(1);
chmod($path, 0600); // changes the inode

clearstatcache();   // discard the cached stat result
$second = filectime($path);

echo ($second >= $first) ? "ctime updated\n" : "still cached\n";

unlink($path);

Isso imprime ctime updated. Remova a linha clearstatcache() e o PHP pode reportar o valor antigo em vez disso.

Conclusão

A função filectime() é uma ferramenta útil em PHP para verificar quando o inode (metadados) de um arquivo foi alterado pela última vez — permissões, propriedade ou uma renomeação. Lembre-se de que, apesar do "c", ela não é uma função de horário de criação: use filemtime() quando precisar do horário da última modificação de conteúdo, fileatime() para o horário do último acesso, e chame clearstatcache() quando precisar de uma leitura com garantia de atualização dentro da mesma requisição. Combine-a com file_exists() para evitar avisos em arquivos inexistentes.

Prática