ftp_mdtm()

Qu'est-ce que ftp_mdtm() ?

La fonction ftp_mdtm() est une fonction intégrée de PHP qui récupère la date de dernière modification d'un seul fichier sur un serveur FTP. « mdtm » signifie modification time (heure de modification) — elle correspond directement à la commande MDTM du protocole FTP.

Elle est particulièrement utile lorsque vous souhaitez synchroniser des fichiers, détecter des modifications, ou décider si vous devez re-télécharger quelque chose : au lieu de récupérer le fichier entier pour vérifier s'il est plus récent que votre copie locale, vous demandez d'abord à l'horodatage du serveur.

Elle prend deux paramètres :

1. ftp — l'identifiant de connexion retourné par ftp_connect().
2. remote_file — le chemin vers le fichier sur le serveur.

La fonction retourne la date de dernière modification sous forme d'horodatage Unix (secondes depuis le 1970-01-01 UTC). En cas d'échec — le fichier n'existe pas, le chemin pointe vers un répertoire, ou la connexion est invalide — elle retourne -1.

ftp_mdtm() fonctionne uniquement sur les fichiers ordinaires. De nombreux serveurs rejettent MDTM pour les répertoires, donc l'appeler sur un dossier retourne généralement -1.

Syntaxe de ftp_mdtm()

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

Le type resource était utilisé jusqu'à PHP 7. À partir de PHP 8.1, les connexions FTP sont des objets (FTP\Connection), donc le premier argument est une instance FTP\Connection — mais vous passez toujours ce que ftp_connect() a retourné, de sorte que le code existant continue à fonctionner sans modification.

Cette fonction nécessite une connexion FTP active. Elle n'active pas le mode passif pour vous ; si votre réseau est derrière un pare-feu ou un NAT, appelez ftp_pasv($ftp, true) après la connexion et avant de demander l'horodatage.

Utilisation de base

Pour utiliser ftp_mdtm(), connectez-vous d'abord avec ftp_connect() et authentifiez-vous avec 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 l'horodatage en date lisible

Comme ftp_mdtm() retourne un horodatage Unix brut, vous le formatez presque toujours avec date() avant de l'afficher à un utilisateur. La conversion est en PHP pur, donc elle fonctionne partout — sans serveur FTP nécessaire :

<?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";

Sortie :

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

MDTM retourne l'heure en UTC. Utilisez gmdate() (ou définissez explicitement le fuseau horaire) pour que l'heure affichée ne soit pas décalée silencieusement par le fuseau horaire local de votre serveur. Consultez date() pour la liste complète des caractères de format.

Gestion des erreurs dans ftp_mdtm()

Puisque la fonction retourne -1 en cas d'échec, vérifiez cette valeur avec l'opérateur de comparaison strict ===. Un == souple correspondrait aussi à false et à d'autres valeurs fausses, masquant les vrais résultats :

<?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";
}

Cas d'utilisation courant : télécharger uniquement si plus récent

La raison habituelle d'appeler ftp_mdtm() est d'éviter de re-télécharger un fichier inchangé. Comparez l'horodatage distant avec la date de modification de votre fichier 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";
}

Ce schéma maintient l'efficacité des miroirs et des sauvegardes : vous ne transférez des octets que lorsque la copie du serveur est réellement plus récente.

Points d'attention

• La prise en charge varie selon les serveurs. MDTM ne fait pas partie du standard FTP original, donc certains serveurs plus anciens ou restreints ne l'implémentent pas et retournent toujours -1, même pour des fichiers existants.
• Les répertoires retournent -1. Utilisez ftp_nlist() pour lister le contenu des répertoires à la place.
• Fuseau horaire. Les horodatages sont en UTC ; formatez avec gmdate() pour éviter un décalage inattendu.
• Besoin aussi de la taille du fichier ? Combinez avec ftp_size().

Conclusion

ftp_mdtm() récupère l'horodatage Unix de dernière modification d'un fichier sur un serveur FTP, ce qui en fait la brique de base pour la détection des modifications et la synchronisation incrémentielle. N'oubliez pas de vérifier la valeur d'échec -1 avec ===, de formater le résultat avec date() ou gmdate(), et d'activer le mode passif lorsque votre réseau l'exige.

Pratique