ftp_mlsd()

Qu'est-ce que ftp_mlsd() ?

ftp_mlsd() est une fonction PHP intégrée (disponible depuis PHP 7.2) qui liste le contenu d'un répertoire sur un serveur FTP en utilisant la commande FTP MLSD. Contrairement aux anciennes fonctions de listage, elle renvoie un résultat structuré et lisible par machine : au lieu d'un bloc de texte brut à analyser soi-même, vous obtenez un array d'entrées où chaque fichier ou répertoire porte des attributs nommés tels que son type, sa taille et sa date de modification.

C'est important car les listings de répertoires FTP sont notoirement inconsistants — ftp_rawlist() renvoie des lignes dont le format dépend du système d'exploitation du serveur. La commande MLSD a été ajoutée au protocole FTP (RFC 3659) précisément pour standardiser cela, et ftp_mlsd() l'expose directement.

Utilisez ftp_mlsd() lorsque vous avez besoin de :

• Énumérer des fichiers et connaître la taille, le type ou l'horodatage de chacun.
• Distinguer de manière fiable les répertoires des fichiers (l'attribut type s'en charge pour vous).
• Éviter l'analyse de chaînes fragile qu'impose ftp_rawlist().

Si vous avez seulement besoin d'une liste plate de noms de fichiers, ftp_nlist() est plus simple. Si vous devez prendre en charge des serveurs antérieurs à la version 7.2 ou des serveurs sans support MLSD, repliez-vous sur ftp_rawlist().

Syntaxe de ftp_mlsd()

ftp_mlsd(FTP\Connection $ftp, string $directory): array|false

La fonction prend deux paramètres obligatoires :

Elle renvoie un array d'entrées en cas de succès, ou false en cas d'échec (par exemple, si le chemin n'existe pas ou si le serveur ne prend pas en charge MLSD).

Ce que retourne ftp_mlsd()

Chaque élément du array renvoyé est un tableau associatif décrivant une entrée. Les clés exactes dépendent de ce que le serveur rapporte, mais les plus courantes sont :

La structure d'une entrée unique ressemble à ceci :

[
    'name'   => 'report.pdf',
    'type'   => 'file',
    'size'   => '20480',
    'modify' => '20240115093000', // 2024-01-15 09:30:00
    'perms'  => 'adfr',
]

Utilisation de ftp_mlsd()

Avant de lister quoi que ce soit, vous vous connectez avec ftp_connect() et vous authentifiez avec ftp_login(). Le flux complet ressemble à ceci :

<?php

// 1. Open a connection
$ftp = ftp_connect('ftp.example.com');

// 2. Authenticate
ftp_login($ftp, 'username', 'password');

// 3. Switch to passive mode (recommended behind firewalls/NAT)
ftp_pasv($ftp, true);

// 4. Get a structured listing of the directory
$entries = ftp_mlsd($ftp, '/public_html');

// 5. Always close the connection when done
ftp_close($ftp);

Itérer sur le listing

La véritable valeur de ftp_mlsd() réside dans les données structurées. Ici, nous affichons chaque fichier avec une taille lisible par l'homme et ignorons les pseudo-entrées . et .. :

<?php

$entries = ftp_mlsd($ftp, '.');

foreach ($entries as $entry) {
    // Skip the current-dir and parent-dir markers
    if (in_array($entry['type'], ['cdir', 'pdir'], true)) {
        continue;
    }

    if ($entry['type'] === 'dir') {
        echo "[DIR]  {$entry['name']}\n";
    } else {
        $kb = round($entry['size'] / 1024, 1);
        echo "[FILE] {$entry['name']} ({$kb} KB)\n";
    }
}

Le champ modify est un horodatage de 14 chiffres. Vous pouvez le convertir en une date réelle avec DateTime :

<?php

$modified = DateTime::createFromFormat('YmdHis', $entry['modify']);
echo $modified->format('Y-m-d H:i:s');

Gestion des erreurs dans ftp_mlsd()

ftp_mlsd() renvoie false en cas d'échec, donc vérifiez toujours le résultat avant d'itérer dessus — appeler foreach sur false émettrait un avertissement et ne traiterait rien.

<?php

$entries = ftp_mlsd($ftp, '/path/that/may/not/exist');

if ($entries === false) {
    echo "Failed to retrieve the directory listing.\n";
} else {
    foreach ($entries as $entry) {
        echo $entry['name'] . "\n";
    }
}

Raisons courantes pour lesquelles ftp_mlsd() échoue :

• Le serveur ne prend pas en charge la commande MLSD (serveurs FTP anciens ou minimaux). Repliez-vous sur ftp_rawlist().
• Le chemin du répertoire est incorrect ou vous n'avez pas la permission de le lire.
• Vous n'êtes pas encore connecté, ou la connexion a expiré.

ftp_mlsd() par rapport aux autres fonctions de listage

Conclusion

ftp_mlsd() est la manière moderne et fiable de lister un répertoire FTP en PHP : elle vous fournit un array structuré avec le type, la taille et la date de modification de chaque entrée, vous épargnant l'analyse de texte fragile qu'exigent les anciennes fonctions. Associez-la à ftp_connect(), ftp_login() et ftp_close() pour un workflow de listage FTP complet et robuste — et n'oubliez pas de vérifier === false avant d'itérer.

Pratique