touch()

Introdução

Em PHP, a função touch() é usada para definir o tempo de modificação e de acesso de um arquivo. É uma função útil para trabalhar com arquivos em seus scripts PHP. Neste artigo, abordaremos tudo o que você precisa saber sobre a função touch(), incluindo sua sintaxe, parâmetros e exemplos de como ela pode ser usada.

Entendendo a Função touch()

A função touch() atualiza o tempo de modificação (mtime) e o tempo de acesso (atime) de um arquivo. Ela aceita três parâmetros:

• $filename — o caminho para o arquivo.
• $mtime (opcional) — o timestamp de modificação como tempo Unix. Se omitido, o tempo atual (time()) é usado.
• $atime (opcional) — o timestamp de acesso como tempo Unix. Se omitido, o valor passado para $mtime é usado (não necessariamente o tempo atual).

Se o arquivo especificado não existir, touch() cria um arquivo vazio naquele caminho. Isso o torna o equivalente PHP padrão do comando Unix touch.

Você normalmente recorre ao touch() quando deseja:

• Criar um arquivo reservado vazio ou arquivo de bloqueio.
• "Atualizar" o mtime de um arquivo para que ferramentas de invalidação de cache (ou verificações de build no estilo make) o tratem como recentemente alterado.
• Definir um timestamp conhecido em um arquivo para testes ou para sistemas que comparam tempos de modificação.

Sintaxe da Função touch()

A sintaxe da função touch() é a seguinte:

touch(string $filename, ?int $mtime = null, ?int $atime = null): bool

Aqui, $filename é o caminho para o arquivo, $mtime é o timestamp de modificação no formato Unix e $atime é o timestamp de acesso. Ambos os timestamps são opcionais. A função retorna true em caso de sucesso ou false em caso de falha.

Um timestamp em PHP é simplesmente o número de segundos desde a época Unix (1 de janeiro de 1970). Use time() para "agora", strtotime() para analisar uma string de data, ou aritmética como time() - 3600 para "uma hora atrás".

Exemplos de Uso do touch()

Vamos dar uma olhada em um exemplo de como a função touch() pode ser usada em PHP.

Exemplo 1: Atualizando o Tempo de Modificação e Acesso de um Arquivo

if (touch('example.txt', time())) {
    echo "File timestamps updated successfully.";
} else {
    echo "Failed to update file timestamps. Check permissions or file path.";
}

Este exemplo atualiza o tempo de modificação e de acesso do arquivo example.txt para o tempo atual. A instrução if verifica o valor de retorno booleano para lidar com possíveis erros, como arquivos ausentes ou permissões insuficientes.

Exemplo 2: Definindo os Tempos de Modificação e Acesso Explicitamente

$mtime = time() - 3600; // 1 hour ago
$atime = time() - 1800; // 30 minutes ago

if (touch('example.txt', $mtime, $atime)) {
    echo "Both timestamps updated successfully.";
} else {
    echo "Failed to update timestamps.";
}

Este exemplo demonstra como passar os parâmetros $mtime e $atime para definir valores diferentes para os tempos de modificação e de acesso.

Exemplo 3: Criando um Arquivo Reservado

Como touch() cria o arquivo quando ele está ausente, é uma forma concisa de criar um arquivo vazio sem abrir um stream:

$path = 'cache/.gitkeep';

if (!file_exists($path)) {
    touch($path);
    echo "Placeholder created.";
} else {
    echo "Placeholder already exists.";
}

Após chamar touch(), você pode ler o novo tempo de modificação com filemtime() para confirmar a alteração:

$timestamp = mktime(0, 0, 0, 1, 1, 2030); // Jan 1, 2030 (in the default timezone)
touch('example.txt', $timestamp);
echo filemtime('example.txt') === $timestamp ? 'mtime set' : 'mismatch';

Nota: Certifique-se de que o processo PHP tenha permissões de escrita no diretório de destino. Se o arquivo não existir, touch() irá criá-lo com permissões padrão (sujeitas ao umask do sistema). Definir um mtime no futuro é permitido e às vezes é usado para forçar reconstruções de cache.

Conclusão

A função touch() fornece uma maneira direta de gerenciar timestamps de arquivos em PHP. Seja para atualizar tempos de acesso para sistemas de cache, rastrear atividade de arquivos ou criar arquivos reservados, essa função se integra perfeitamente aos seus fluxos de trabalho de manipulação de arquivos. Esperamos que este guia tenha esclarecido como usar touch() de forma eficaz em seus projetos.

Funções Relacionadas

• filemtime() — lê o último tempo de modificação de um arquivo.
• file_exists() — verifica se um arquivo ou diretório existe antes de usar touch nele.
• fopen() — abre ou cria um arquivo quando você também precisa escrever conteúdo.
• unlink() — exclui um arquivo.
• date() — formata os timestamps Unix com os quais touch() trabalha.

Prática