ftp_raw()

Comprendre la fonction PHP ftp_raw()

La fonction ftp_raw() est une fonction PHP intégrée qui envoie une commande arbitraire directement à un serveur FTP et retourne la réponse brute et non analysée du serveur. Contrairement aux fonctions FTP de plus haut niveau, ftp_raw() n'interprète pas le résultat pour vous — elle retourne exactement ce que le serveur a répondu, ligne par ligne. Cette page explique ce que fait la fonction, quand vous en avez réellement besoin, et comment l'utiliser en toute sécurité.

Qu'est-ce que ftp_raw() ?

FTP est un protocole texte : les clients envoient de courtes commandes comme SYST, PWD ou FEAT, et le serveur répond avec des lignes de statut numérotées (par exemple 215 UNIX Type: L8). La plupart des fonctions PHP FTP — telles que ftp_nlist(), ftp_get() et ftp_systype() — encapsulent l'une de ces commandes et analysent la réponse pour en extraire une valeur pratique. ftp_raw() ignore cette analyse et expose directement le protocole.

Elle prend deux paramètres :

1. ftp_stream — l'identifiant de connexion retourné par ftp_connect().
2. command — la chaîne de commande FTP à envoyer (par exemple 'SYST' ou 'PWD').

En cas de succès, elle retourne un array de chaînes, un élément par ligne de réponse, contenant la réponse du serveur. En cas d'échec (par exemple une connexion invalide), elle retourne false.

Quand faut-il l'utiliser ?

Pour les tâches courantes — listing, upload, téléchargement — privilégiez les fonctions dédiées ; elles gèrent les connexions de données et l'analyse à votre place. Utilisez ftp_raw() uniquement lorsque :

• Vous avez besoin d'une commande pour laquelle PHP ne fournit pas de wrapper (par exemple FEAT pour découvrir les fonctionnalités du serveur, ou une directive SITE personnalisée).
• Vous déboguez et souhaitez voir la ligne de statut exacte que le serveur retourne.
• Vous implémentez un comportement de protocole que l'API de haut niveau n'expose pas.

Notez que ftp_raw() est destinée aux commandes du canal de contrôle uniquement. Elle ne peut pas transférer des données de fichier — les commandes comme RETR ou LIST nécessitent une connexion de données séparée, c'est pourquoi vous utilisez ftp_get() ou ftp_nlist() pour cela.

Commandes brutes courantes

Syntaxe de ftp_raw()

La signature de la fonction ftp_raw() est la suivante :

ftp_raw(FTP\Connection $ftp, string $command): array

Le paramètre $ftp est la connexion retournée par ftp_connect(), et $command est la chaîne de commande à envoyer. Les deux sont obligatoires.

Utilisation de ftp_raw()

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

<?php

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

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

// Ask the server what operating system it runs
$response = ftp_raw($conn, 'SYST');

// Output the server's raw response, one line per element
echo "Server response: " . implode("\n", $response) . "\n";
// e.g. Server response: 215 UNIX Type: L8

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

Ici, nous nous connectons avec ftp_connect() et vérifions que la connexion a réussi, nous nous authentifions avec ftp_login(), nous envoyons la commande SYST avec ftp_raw(), et nous affichons chaque ligne de réponse. Le 215 est le code de réponse FTP ; le texte qui suit est la réponse du serveur. Enfin, nous libérons la connexion avec ftp_close().

Gestion des erreurs dans ftp_raw()

Vérifiez toujours la valeur de retour avant de l'utiliser. ftp_raw() retourne false quand elle ne peut pas envoyer la commande (par exemple parce que la connexion n'est plus valide), donc passer ce résultat directement dans implode() déclencherait une erreur de type. Protégez-vous contre cela :

<?php

$response = ftp_raw($conn, 'SYST');

if ($response === false) {
    echo "Failed to send the raw command to the FTP server.\n";
} else {
    echo implode("\n", $response) . "\n";
}

ftp_close($conn);

Gardez à l'esprit qu'un array non-false ne garantit pas que la commande elle-même a réussi — cela signifie seulement que le serveur a répondu. Inspectez le code de réponse (le nombre en tête de chaque ligne, comme 5xx pour les erreurs) lorsque vous devez savoir si la commande a été acceptée.

Conclusion

La fonction ftp_raw() vous donne un accès direct au canal de contrôle FTP, ce qui est inestimable pour les commandes que PHP n'encapsule pas (comme FEAT) et pour le débogage. Pour les opérations courantes de listing, d'upload et de téléchargement, préférez les fonctions dédiées. Consultez la référence complète des fonctions PHP FTP pour l'ensemble complet.

Pratique