ftp_rawlist() - Apprendre PHP

Comprendre la fonction PHP ftp_rawlist()

La fonction ftp_rawlist() retourne un listing détaillé d'un répertoire sur un serveur FTP. Chaque élément du tableau qu'elle retourne est une ligne brute de la sortie LIST du serveur — le même texte que vous verriez dans un client FTP en ligne de commande, incluant les permissions, le propriétaire, la taille et la date de modification.

Cette page explique ce que retourne ftp_rawlist(), sa syntaxe, un exemple complet fonctionnel, comment analyser les lignes brutes pour en extraire des données exploitables, les listings récursifs et la gestion des erreurs. Si vous avez seulement besoin des noms de fichiers d'un répertoire, utilisez plutôt ftp_nlist() — c'est plus simple et bien plus facile à analyser.

Qu'est-ce que ftp_rawlist() ?

ftp_rawlist() accepte deux paramètres obligatoires et un paramètre optionnel :

ftp_stream — l'objet de connexion (PHP 8.1+) ou la ressource retournée par ftp_connect() (ou ftp_ssl_connect()).
directory — le répertoire à lister.
recursive (optionnel) — à définir à true pour lister les sous-répertoires de façon récursive.

En cas de succès, elle retourne un array de chaînes, où chaque string est une ligne brute de la sortie ; en cas d'échec (ou pour un répertoire vide illisible), elle retourne false.

L'essentiel à comprendre est que cette sortie n'est pas standardisée. Il s'agit de ce qu'émet la commande LIST du serveur, donc son format dépend du système d'exploitation et de la configuration du serveur. Un serveur de style Unix retourne généralement des lignes ressemblant à la sortie de ls -l :

drwxr-xr-x   2 owner group        4096 Jun 21 10:00 images
-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html

Les serveurs de style Windows/DOS retournent une mise en forme entièrement différente. Pour cette raison, ftp_rawlist() vous offre des détails complets au prix d'un parsing du texte libre. Comparaison avec :

ftp_nlist() — retourne un simple array de noms de fichiers uniquement.
ftp_mlsd() — retourne un listing structuré et lisible par une machine (préférable quand le serveur supporte la commande MLSD).

Syntaxe de ftp_rawlist()

La syntaxe de la fonction ftp_rawlist() est la suivante :

Syntaxe de ftp_rawlist()

array ftp_rawlist ( FTP\Connection|resource $ftp_stream , string $directory [, bool $recursive = false ] )

La fonction ftp_rawlist() prend deux paramètres obligatoires, ftp_stream et directory. Le paramètre ftp_stream est l'identifiant de connexion retourné par la fonction ftp_connect(), et le paramètre directory est le répertoire à lister. La fonction possède également un paramètre optionnel, recursive, qui permet de spécifier si les sous-répertoires doivent être listés.

Utilisation de ftp_rawlist()

Pour utiliser la fonction ftp_rawlist(), vous devez d'abord établir une connexion au serveur FTP avec la fonction ftp_connect(). Voici un exemple :

Utilisation de ftp_rawlist()

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

// Get a detailed listing of the directory
$listing = ftp_rawlist($conn, '/public_html');

// Output the listing to the console
if ($listing) {
    foreach ($listing as $item) {
        echo $item . "\n";
    }
}

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

Ici, nous nous connectons avec ftp_connect(), nous authentifions avec ftp_login(), récupérons le listing avec ftp_rawlist(), affichons chaque ligne brute, puis libérons la connexion avec ftp_close().

Conseil — mode passif : De nombreux réseaux et pare-feux bloquent le canal de données en mode actif qu'utilise ftp_rawlist() pour récupérer le listing, ce qui le fait bloquer ou retourner false. Si cela se produit, activez le mode passif avec ftp_pasv($conn, true) après la connexion.

Note de sécurité : Le FTP standard transmet les identifiants et les données en texte clair. Pour les environnements de production, envisagez d'utiliser ftp_ssl_connect() pour du FTP explicite sur TLS, ou passez à SFTP (via l'extension ssh2) pour des transferts chiffrés.

Analyse du listing brut

Chaque ligne étant du texte non structuré, vous souhaitez généralement en extraire des champs individuels. Pour un serveur de style Unix, vous pouvez découper chaque ligne sur les espaces : les permissions sont le premier token, la taille est le cinquième, et le nom de fichier est tout ce qui suit le huitième token (le nom peut contenir des espaces).

Analyse d'un listing brut de style Unix

<?php

// One line of typical ftp_rawlist() output:
$line = '-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html';

// Split on runs of whitespace, limited so the name stays intact.
$parts = preg_split('/\s+/', $line, 9);

$type        = $parts[0][0] === 'd' ? 'directory' : 'file';
$permissions = $parts[0];
$size        = (int) $parts[4];
$name        = $parts[8];

echo "Name:        $name\n";
echo "Type:        $type\n";
echo "Size:        $size bytes\n";
echo "Permissions: $permissions\n";
?>

Cela affiche :

Name:        index.html
Type:        file
Size:        10240 bytes
Permissions: -rw-r--r--

Si votre serveur le supporte, préférez ftp_mlsd(), qui retourne ces données déjà structurées afin d'éviter le fragile parsing de chaînes.

Listing des sous-répertoires de façon récursive

Passer true comme troisième argument demande au serveur de parcourir les sous-répertoires. La sortie contient alors des lignes vides et des en-têtes de répertoire (un chemin suivi d'un deux-points) qui séparent le contenu de chaque sous-répertoire — soyez prêt à les ignorer lors de l'itération :

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html', true);

foreach ($listing as $line) {
    if ($line === '' || str_ends_with($line, ':')) {
        // Skip blank separators and "/path/to/dir:" headers
        continue;
    }
    echo $line . "\n";
}
?>

Notez que tous les serveurs FTP ne respectent pas l'indicateur récursif, et qu'une arborescence profonde peut être lente — testez donc avec votre serveur cible.

Gestion des erreurs dans ftp_rawlist()

Il est important de gérer correctement les erreurs lors de l'utilisation de la fonction ftp_rawlist(). Si la fonction retourne false, cela signifie que l'opération a échoué. Voici un exemple de gestion des erreurs :

Gestion des erreurs dans ftp_rawlist()

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html');

if (!$listing) {
    echo "Failed to get directory listing from FTP server.\n";
}

ftp_close($conn);
?>

En gérant les erreurs de manière appropriée et en vérifiant la valeur de retour de la fonction, vous pouvez garantir le succès de vos opérations FTP avec la fonction ftp_rawlist().

Conclusion

ftp_rawlist() est la fonction à utiliser lorsque vous avez besoin des métadonnées complètes des fichiers — permissions, propriétaire, taille et date — depuis un répertoire FTP, et pas seulement des noms. La contrepartie est que sa sortie correspond au texte LIST brut et dépendant de l'OS du serveur, donc prévoyez de l'analyser (ou utilisez le structuré ftp_mlsd() lorsqu'il est disponible). Vérifiez toujours la valeur de retour, activez le mode passif derrière un pare-feu, et préférez une connexion chiffrée en production.

Fonctions associées

ftp_nlist() — lister les noms de fichiers uniquement
ftp_mlsd() — listing structuré et lisible par une machine
ftp_connect() / ftp_login() — ouvrir et authentifier une session
ftp_get() — télécharger un fichier une fois trouvé
ftp_close() — fermer la connexion

Practice

Pratique

Quel est le rôle de ftp_rawlist en PHP ?

Elle affiche une liste de fichiers dans un répertoire spécifié.Elle fournit des informations sur un fichier sur un serveur.Elle retourne une liste détaillée des fichiers du répertoire donné sur un serveur FTP.Elle récupère le contenu d'un fichier depuis un serveur.