Comprendre la fonction PHP ftp_cdup()

Lorsque vous scriptez des transferts de fichiers via FTP, vous avez souvent besoin de naviguer dans l'arborescence de répertoires distants avant de téléverser, télécharger ou lister des fichiers. L'extension FTP intégrée à PHP vous offre un petit ensemble de fonctions de navigation, et ftp_cdup() est celle qui remonte d'un niveau — l'équivalent FTP de cd .. en ligne de commande.

Ce chapitre explique ce que fait ftp_cdup(), sa syntaxe et sa valeur de retour, un exemple complet fonctionnel, ainsi que les pièges à connaître avant de l'utiliser en production.

Qu'est-ce que ftp_cdup() ?

ftp_cdup() change le répertoire de travail courant sur le serveur FTP distant en son répertoire parent. Elle fait exactement une chose : remonter d'un niveau. Si vous êtes dans /var/www/html/uploads, appeler ftp_cdup() une fois vous amène dans /var/www/html.

C'est le pendant de ftp_chdir(), qui descend dans un répertoire nommé. Utilisez ftp_chdir() pour descendre ou accéder à un chemin, et ftp_cdup() pour remonter vers la racine.

ftp_cdup() affecte uniquement le répertoire courant suivi par votre session FTP. Elle ne déplace, ne copie ni ne supprime quoi que ce soit sur le serveur.

Syntaxe

ftp_cdup(FTP\Connection $ftp): bool

Valeur de retour : true en cas de succès, false en cas d'échec (par exemple, si vous êtes déjà à la racine ou si la connexion n'est pas authentifiée).

À partir de PHP 8.1, ftp_connect() retourne un objet FTP\Connection plutôt qu'une ressource. La fonction fonctionne de la même façon ; seul le type a changé.

Comment utiliser ftp_cdup()

Avant de pouvoir appeler ftp_cdup(), vous devez :

1. Ouvrir une connexion avec ftp_connect().
2. Vous authentifier avec ftp_login().
3. (Généralement) passer en mode passif avec ftp_pasv() pour que les transferts fonctionnent derrière NAT/pare-feu.

L'exemple ci-dessous se connecte, descend dans un sous-répertoire avec ftp_chdir(), puis utilise ftp_cdup() pour remonter d'un niveau. Il affiche le répertoire de travail avant et après avec ftp_pwd() pour que vous puissiez en voir l'effet :

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

// Move into a sub-directory first.
ftp_chdir($ftp, 'uploads');
echo "Before: " . ftp_pwd($ftp) . PHP_EOL; // e.g. /uploads

// Step back up to the parent directory.
if (ftp_cdup($ftp)) {
    echo "After:  " . ftp_pwd($ftp) . PHP_EOL; // e.g. /
} else {
    echo "Failed to change to the parent directory" . PHP_EOL;
}

ftp_close($ftp);

Ici, nous nous connectons, nous nous authentifions et nous activons le mode passif. Nous descendons ensuite dans uploads, confirmons l'emplacement avec ftp_pwd(), puis appelons ftp_cdup() pour revenir au répertoire parent. Le test if nous permet de réagir lorsque le déplacement échoue plutôt que de supposer qu'il a réussi. Enfin, nous libérons la connexion avec ftp_close().

Pièges courants

• Vous êtes déjà à la racine. Appeler ftp_cdup() depuis le sommet de l'arborescence retourne false. Vérifiez toujours la valeur de retour plutôt que de supposer le succès.
• La confondre avec une opération sur les fichiers. ftp_cdup() modifie uniquement votre position. Pour supprimer ou renommer des éléments distants, utilisez ftp_delete() ou ftp_rename().
• Avertissements en cas d'échec. Un appel échoué génère également un E-WARNING. Supprimez-le ou gérez-le selon votre stratégie de gestion des erreurs, mais ne comptez jamais sur la suppression au lieu de vérifier le résultat boolean.
• Oublier le mode passif. Si les listings ou les transferts se bloquent après la navigation, vous avez probablement omis ftp_pasv($ftp, true).

Conclusion

ftp_cdup() est l'outil de navigation le plus simple de la boîte à outils FTP de PHP : il remonte le répertoire courant de la session d'un niveau et retourne un boolean indiquant si l'opération a réussi. Associez-le à ftp_chdir() pour descendre et à ftp_pwd() pour confirmer votre position, et vous disposez de tout le nécessaire pour parcourir de manière fiable une arborescence de répertoires distants.

Pratique