ftp_nlist()

La fonction PHP ftp_nlist()

ftp_nlist() retourne un array plat des noms des fichiers et sous-répertoires contenus dans un répertoire d'un serveur FTP. C'est l'équivalent FTP de la commande nls/ls — vous obtenez uniquement les noms, sans information sur la taille, les permissions ou les dates.

Cette page couvre la syntaxe et les paramètres, un exemple complet et fonctionnel, à quoi ressemble la valeur de retour, comment gérer les échecs, les pièges courants (mode passif, noms sans préfixe de chemin), et quand utiliser ftp_rawlist() à la place.

Syntaxe

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

Valeur de retour : un array de noms en cas de succès, ou false en cas d'échec.

Les noms retournés n'incluent pas le préfixe du répertoire — lister /public_html/ vous donnera index.php, et non /public_html/index.php. Si le répertoire est vide, vous obtenez un array vide [], ce qui n'est pas la même chose que false.

Un exemple complet

Avant de pouvoir lister quoi que ce soit, vous avez besoin d'une connexion ouverte et authentifiée. Le flux typique est ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close() :

Utilisation de ftp_nlist()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to FTP server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Enable passive mode (often required for directory listings)
ftp_pasv($conn, true);

// Get an array of filenames in the specified directory
$files = ftp_nlist($conn, '/public_html/');

// Output the array of filenames
print_r($files);

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

Chaque étape est protégée : nous abandonnons si la connexion ou la connexion échoue. Activer le mode passif avec ftp_pasv() est important — de nombreux serveurs (et la plupart des pare-feux) l'exigent avant qu'un listage de répertoire puisse réussir. Ainsi, un appel manquant à ftp_pasv() est la cause la plus fréquente pour laquelle ftp_nlist() retourne silencieusement false.

Pour un répertoire contenant deux fichiers, print_r() afficherait quelque chose comme :

Array
(
    [0] => index.php
    [1] => style.css
)

ftp_nlist() vs ftp_rawlist()

Utilisez la fonction qui correspond à vos besoins :

• ftp_nlist() retourne simplement un array de noms — parfait pour vérifier si un fichier existe ou pour itérer sur des téléchargements.
• ftp_rawlist() retourne la sortie brute et non analysée de LIST (une string par ligne, comme ls -l), qui inclut les tailles, les permissions et les dates — utile lorsque vous avez besoin de ces métadonnées et êtes prêt à les analyser.

Si vous n'avez besoin que des noms, préférez ftp_nlist() : sa sortie est cohérente entre les serveurs, tandis que le format de ftp_rawlist() varie selon le type de serveur FTP.

Gestion des erreurs

Il est important de gérer correctement les erreurs lors de l'utilisation de la fonction ftp_nlist(). Si la fonction retourne false, cela signifie que le listage a échoué. Notez qu'un répertoire vide retourne un array vide [], et non false. Voici un exemple de gestion des erreurs :

Gestion des erreurs avec ftp_nlist()

<?php

// $conn is assumed to be established from the previous example
$file_list = ftp_nlist($conn, '/public_html/');

if ($file_list === false) {
    echo "Failed to list directory on remote server.\n";
}

ftp_close($conn);

Comparez toujours avec === (égalité stricte). Utiliser un if (!$file_list) souple traiterait un répertoire légitimement vide ([]) comme une erreur, puisqu'un array vide est falsy en PHP.

Pièges courants

• Oublier le mode passif. Appelez ftp_pasv($conn, true) après la connexion si les listages retournent false.
• Array vide vs false. [] signifie "le répertoire existe mais est vide" ; false signifie que le listage a échoué. Distinguez-les avec ===.
• Les noms n'incluent pas le chemin. Ajoutez vous-même le répertoire lorsque vous avez besoin d'un chemin complet : $dir . '/' . $name.
• Fichiers cachés. Certains serveurs omettent les fichiers dot (.htaccess) dans ftp_nlist(). Passez -a via l'argument de répertoire (par ex. '-a /public_html/') sur les serveurs qui le supportent.

Conclusion

ftp_nlist() est le moyen le plus simple d'obtenir les noms des fichiers dans un répertoire distant. Associez-le à ftp_pasv() pour plus de fiabilité, vérifiez la valeur de retour avec ===, et utilisez ftp_rawlist() lorsque vous avez également besoin des métadonnées des fichiers. Pour le flux de travail FTP complet, consultez l'aperçu PHP FTP.

Pratique