ftp_mdtm()

¿Qué es ftp_mdtm()?

La función ftp_mdtm() es una función integrada de PHP que obtiene la hora de última modificación de un archivo en un servidor FTP. "mdtm" significa modification time (tiempo de modificación) — se corresponde directamente con el comando MDTM del protocolo FTP.

Es más útil cuando deseas sincronizar archivos, detectar cambios o decidir si volver a descargar algo: en lugar de descargar el archivo completo solo para ver si es más reciente que tu copia local, primero le preguntas al servidor por su marca de tiempo.

Recibe dos parámetros:

1. ftp — el identificador de conexión devuelto por ftp_connect().
2. remote_file — la ruta al archivo en el servidor.

La función devuelve la hora de última modificación como un timestamp Unix (segundos desde 1970-01-01 UTC). En caso de error — el archivo no existe, la ruta apunta a un directorio o la conexión no es válida — devuelve -1.

ftp_mdtm() funciona solo con archivos regulares. Muchos servidores rechazan MDTM para directorios, por lo que llamarla sobre una carpeta generalmente devuelve -1.

Sintaxis de ftp_mdtm()

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

El tipo resource se utilizaba hasta PHP 7. A partir de PHP 8.1, las conexiones FTP son objetos (FTP\Connection), por lo que el primer argumento es una instancia de FTP\Connection — aunque seguirás pasando lo que devuelva ftp_connect(), por lo que el código existente sigue funcionando sin cambios.

Esta función requiere una conexión FTP activa. No activa el modo pasivo por ti; si tu red está detrás de un firewall o NAT, llama a ftp_pasv($ftp, true) después de iniciar sesión y antes de solicitar la marca de tiempo.

Uso básico

Para usar ftp_mdtm(), primero conéctate con ftp_connect() y autentícate con 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);

Convertir el timestamp en una fecha legible

Como ftp_mdtm() devuelve un timestamp Unix sin formato, casi siempre lo formatearás con date() antes de mostrárselo a un usuario. La conversión es PHP puro, así que funciona en cualquier entorno — no se necesita 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";

Salida:

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

MDTM devuelve la hora en UTC. Usa gmdate() (o establece la zona horaria explícitamente) para que la hora mostrada no se vea desplazada silenciosamente por la zona horaria local del servidor. Consulta date() para ver la lista completa de caracteres de formato.

Manejo de errores en ftp_mdtm()

Dado que la función devuelve -1 en caso de error, comprueba ese valor con el operador de comparación estricta ===. Una comparación laxa == también coincidiría con false y otros valores falsy, ocultando resultados reales:

<?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 frecuente: descargar solo si es más reciente

La razón habitual para llamar a ftp_mdtm() es evitar volver a descargar un archivo sin cambios. Compara la marca de tiempo remota con la hora de modificación de tu archivo 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";
}

Este patrón mantiene la eficiencia de los espejos y copias de seguridad: solo transferirás bytes cuando la copia del servidor sea realmente más reciente.

Consideraciones

• El soporte del servidor varía. MDTM no forma parte del estándar FTP original, por lo que algunos servidores más antiguos o restringidos no lo implementan y siempre devuelven -1, incluso para archivos que existen.
• Los directorios devuelven -1. Usa ftp_nlist() para listar el contenido de un directorio.
• Zona horaria. Los timestamps están en UTC; formatea con gmdate() para evitar un desplazamiento inesperado.
• ¿También necesitas el tamaño del archivo? Combínalo con ftp_size().

Conclusión

ftp_mdtm() obtiene el timestamp Unix de última modificación de un archivo en un servidor FTP, lo que la convierte en el bloque fundamental para la detección de cambios y la sincronización incremental. Recuerda comprobar el valor de error -1 con ===, formatear el resultado con date() o gmdate(), y activar el modo pasivo cuando tu red lo requiera.

Práctica