ftp_mdtm()

O que é ftp_mdtm()?

A função ftp_mdtm() é uma função nativa do PHP que obtém a data da última modificação de um único arquivo em um servidor FTP. "mdtm" significa modification time (tempo de modificação) — ela corresponde diretamente ao comando MDTM do protocolo FTP.

É mais útil quando você deseja sincronizar arquivos, detectar alterações ou decidir se deve fazer o download novamente: em vez de baixar o arquivo inteiro apenas para verificar se ele é mais recente que sua cópia local, você solicita ao servidor o seu timestamp primeiro.

Ela recebe dois parâmetros:

1. ftp — o identificador de conexão retornado por ftp_connect().
2. remote_file — o caminho para o arquivo no servidor.

A função retorna a data da última modificação como um timestamp Unix (segundos desde 1970-01-01 UTC). Em caso de falha — o arquivo não existe, o caminho aponta para um diretório ou a conexão é inválida — ela retorna -1.

ftp_mdtm() funciona apenas com arquivos regulares. Muitos servidores rejeitam MDTM para diretórios, portanto chamá-la em uma pasta normalmente retorna -1.

Sintaxe de ftp_mdtm()

ftp_mdtm(resource|FTP\Connection $ftp, string $remote_file): int

O tipo resource era usado até o PHP 7. A partir do PHP 8.1, as conexões FTP são objetos (FTP\Connection), portanto o primeiro argumento é uma instância de FTP\Connection — mas você ainda passa o que ftp_connect() retornou, de modo que o código existente continua funcionando sem alterações.

Esta função requer uma conexão FTP ativa. Ela não ativa o modo passivo automaticamente; se a sua rede estiver atrás de um firewall ou NAT, chame ftp_pasv($ftp, true) após o login e antes de solicitar o timestamp.

Uso básico

Para usar ftp_mdtm(), primeiro conecte-se com ftp_connect() e autentique-se com ftp_login():

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Log in with your FTP credentials
ftp_login($conn, 'username', 'password');

// Enable passive mode (often required behind a firewall)
ftp_pasv($conn, true);

// Get the last modified time of the remote file (a Unix timestamp)
$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

// Close the FTP connection
ftp_close($conn);

Convertendo o timestamp em uma data legível

Como ftp_mdtm() retorna um timestamp Unix bruto, você quase sempre o formata com date() antes de exibi-lo para um usuário. A conversão é PHP puro, portanto funciona em qualquer lugar — sem necessidade de servidor FTP:

<?php

// Pretend ftp_mdtm() returned this timestamp
$last_modified = 1718000000;

echo "Raw timestamp: $last_modified\n";
echo "Formatted (UTC): " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
echo "Year only: " . gmdate('Y', $last_modified) . "\n";

Saída:

Raw timestamp: 1718000000
Formatted (UTC): 2024-06-10 06:13:20 UTC
Year only: 2024

MDTM retorna o horário em UTC. Use gmdate() (ou defina o fuso horário explicitamente) para que o horário exibido não seja deslocado silenciosamente pelo fuso horário local do seu servidor. Consulte date() para a lista completa de caracteres de formato.

Tratamento de erros em ftp_mdtm()

Como a função retorna -1 em caso de falha, verifique esse valor com o operador de comparação estrita ===. Uma comparação fraca == também corresponderia a false e outros valores falsos, ocultando resultados reais:

<?php

$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

if ($last_modified === -1) {
    echo "Failed to retrieve the last modified time.\n";
} else {
    echo "Last modified: " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
}

Caso de uso comum: baixar somente se for mais recente

O motivo típico para chamar ftp_mdtm() é evitar baixar novamente um arquivo que não foi alterado. Compare o timestamp remoto com o tempo de modificação do seu arquivo local:

<?php

$remote = '/path/to/remote/file.txt';
$local  = 'file.txt';

$remoteTime = ftp_mdtm($conn, $remote);

if ($remoteTime === -1) {
    echo "Could not read remote timestamp.\n";
} elseif (!file_exists($local) || $remoteTime > filemtime($local)) {
    echo "Remote file is newer — downloading.\n";
    ftp_get($conn, $local, $remote, FTP_BINARY);
} else {
    echo "Local copy is up to date — skipping download.\n";
}

Esse padrão mantém espelhos e backups eficientes: você transfere bytes apenas quando a cópia do servidor é realmente mais recente.

Problemas comuns

• O suporte varia conforme o servidor. MDTM não faz parte do padrão FTP original, portanto alguns servidores mais antigos ou restritos não o implementam e sempre retornam -1, mesmo para arquivos que existem.
• Diretórios retornam -1. Use ftp_nlist() para listar o conteúdo de diretórios.
• Fuso horário. Os timestamps estão em UTC; formate com gmdate() para evitar um deslocamento inesperado.
• Precisa também do tamanho do arquivo? Combine com ftp_size().

Conclusão

ftp_mdtm() obtém o timestamp Unix da última modificação de um arquivo em um servidor FTP, tornando-a o bloco de construção para detecção de alterações e sincronização incremental. Lembre-se de verificar o valor de falha -1 com ===, formatar o resultado com date() ou gmdate(), e habilitar o modo passivo quando sua rede exigir.

Prática