ftp_pasv()

La fonction PHP ftp_pasv()

La fonction ftp_pasv() active ou désactive le mode passif pour une connexion FTP ouverte. Le mode passif contrôle quel côté ouvre le canal de données lors d'un transfert, et le configurer correctement est la correction la plus courante lorsque les téléchargements FTP et les listes de répertoires se bloquent ou expirent. Ce chapitre explique ce qu'est le mode passif, quand vous en avez besoin et comment appeler ftp_pasv() correctement dans un vrai script de transfert.

Mode actif vs mode passif

FTP utilise deux canaux distincts : un canal de commande (où vous envoyez LIST, RETR, etc.) et un canal de données (où transitent les octets réels du fichier ou la liste). Les deux modes diffèrent uniquement en ce qui concerne celui qui ouvre le canal de données :

• Mode actif (par défaut dans le protocole) : le serveur ouvre la connexion de données vers le client. Si le client se trouve derrière un pare-feu ou un routeur NAT, cette connexion entrante est généralement bloquée, ce qui provoque le blocage du transfert.
• Mode passif : le client ouvre les deux canaux vers le serveur. Comme le client n'effectue que des connexions sortantes, cela fonctionne avec presque tous les pare-feux ou configurations NAT.

C'est pourquoi le mode passif est la valeur par défaut sûre pour la plupart des scripts modernes : les clients sont presque toujours derrière un NAT, tandis que les serveurs sont accessibles via une adresse publique.

Syntaxe

ftp_pasv(FTP\Connection $ftp, bool $passive): bool

• $ftp — la connexion FTP retournée par ftp_connect(). À partir de PHP 8.1, il s'agit d'un objet FTP\Connection ; en PHP 8.0 et versions antérieures, c'était une ressource. Le code existant continue de fonctionner dans les deux cas.
• $passive — true pour activer le mode passif, false pour revenir au mode actif.

La fonction retourne true en cas de succès et false en cas d'échec.

L'ordre est important : appelez ftp_pasv() après ftp_login() et avant tout transfert tel que ftp_get(), ftp_put() ou ftp_nlist(). L'appeler avant la connexion échoue car le mode passif est négocié dans une session authentifiée.

Un transfert complet en mode passif

L'exemple ci-dessous se connecte, s'authentifie, passe en mode passif, télécharge un fichier et effectue le nettoyage. Chaque étape vérifie sa valeur de retour afin que les échecs soient signalés plutôt qu'ignorés silencieusement.

<?php

// 1. Connect to the FTP server (30-second timeout)
$ftp = ftp_connect('ftp.example.com', 21, 30);
if (!$ftp) {
    die("Could not connect to the FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    die("FTP login failed.\n");
}

// 3. Switch to passive mode — must come after login, before any transfer
if (!ftp_pasv($ftp, true)) {
    ftp_close($ftp);
    die("Could not switch to passive mode.\n");
}

// 4. Download a file now that the data channel will be client-initiated
if (ftp_get($ftp, 'local-copy.txt', 'remote/report.txt', FTP_BINARY)) {
    echo "File downloaded successfully.\n";
} else {
    echo "File download failed.\n";
}

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

Sans la ligne ftp_pasv($ftp, true), l'étape 4 se bloquerait fréquemment derrière un routeur NAT car le serveur ne pourrait pas ouvrir la connexion de données entrante.

Gestion des échecs

ftp_pasv() retourne false quand le serveur refuse le changement de mode ou que la connexion n'est plus valide. Vérifiez toujours la valeur de retour avant de tenter un transfert, et utilisez ftp_close() pour libérer la connexion sur chaque chemin de sortie :

<?php

if (!ftp_pasv($ftp, true)) {
    echo "Failed to enable passive mode on the remote server.\n";
    ftp_close($ftp);
    return; // stop before attempting a transfer that would stall
}

Quand utiliser le mode actif à la place

Le mode passif convient à la plupart des clients, mais quelques situations nécessitent le mode actif (ftp_pasv($ftp, false)) :

• La plage de ports passifs du serveur est bloquée par un pare-feu, de sorte que les connexions de données passives sont refusées tandis que les connexions actives réussissent.
• Vous vous connectez depuis un hôte avec une IP publique et sans restrictions entrantes, en communiquant avec un serveur qui n'autorise que les transferts actifs.

Si un transfert se bloque, changer de mode est la première chose à essayer — de nombreux rapports « FTP est cassé » sont simplement le mauvais mode pour le réseau.

Conclusion

ftp_pasv() détermine si le client ou le serveur ouvre le canal de données FTP. Activez-le (true) pour les clients derrière des pare-feux ou du NAT — ce qui représente la plupart des cas — et appelez-le juste après ftp_login() et avant tout transfert. Vérifier sa valeur de retour et fermer la connexion avec ftp_close() rend vos scripts FTP fiables dans différentes configurations réseau.

Pratique