ftp_rename()

La fonction PHP ftp_rename()

ftp_rename() renomme un fichier ou un répertoire sur un serveur FTP distant. Comme FTP ne dispose pas de commande « déplacer » distincte, cette même fonction permet également de déplacer un fichier vers un autre répertoire — il suffit de fournir un nouveau chemin comme nom cible.

Cette page présente la syntaxe, les paramètres et la valeur de retour, un exemple complet de connexion-renommage-déconnexion, la façon de déplacer des fichiers avec le même appel, ainsi que les méthodes de gestion des erreurs nécessaires pour le code en production.

Syntaxe

ftp_rename(FTP\Connection $ftp, string $from, string $to): bool

Avant PHP 8.1, le premier argument était une resource renvoyée par ftp_connect() ; depuis PHP 8.1, il s'agit d'un objet FTP\Connection. Votre code ne change pas — la variable provient toujours directement de ftp_connect().

Paramètres

Valeur de retour

Retourne true en cas de succès et false en cas d'échec. En cas d'échec, PHP émet également un avertissement décrivant la réponse du serveur FTP (par exemple, "550 oldname.txt: No such file or directory").

Un exemple complet

Vous devez ouvrir une connexion et vous authentifier avant d'appeler ftp_rename(). La connexion obtenue via ftp_connect() est transmise à ftp_login(), puis à chaque appel FTP ultérieur :

<?php

// Open an FTP connection (returns false on failure)
$ftp = ftp_connect('ftp.example.com');

if ($ftp === false) {
    exit("Could not connect to the FTP server.\n");
}

// Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("Login failed.\n");
}

// Rename the file
if (ftp_rename($ftp, '/public_html/oldname.txt', '/public_html/newname.txt')) {
    echo "File renamed successfully.\n";
} else {
    echo "File rename failed.\n";
}

// Always close the connection when you are done
ftp_close($ftp);

On se connecte avec ftp_connect(), on s'authentifie avec ftp_login(), on renomme avec ftp_rename(), puis on libère la connexion avec ftp_close(). Vérifier la valeur de retour de chaque étape empêche le script de continuer dans un état défaillant.

Déplacer un fichier vers un autre répertoire

Comme le second argument est un chemin complet, fournir à ftp_rename() une cible dans un répertoire différent déplace le fichier au lieu de simplement le renommer. Le répertoire de destination doit déjà exister — créez-le d'abord avec ftp_mkdir() si nécessaire :

<?php
// Move report.csv from /uploads into /archive (and rename it in the same call)
if (ftp_rename($ftp, '/uploads/report.csv', '/archive/report-2024.csv')) {
    echo "File archived.\n";
} else {
    echo "Move failed — does /archive exist?\n";
}

Gestion des erreurs

ftp_rename() retourne false (et génère un avertissement) lorsque la source n'existe pas, que la cible existe déjà ou que vous ne disposez pas des permissions nécessaires. Testez toujours la valeur de retour plutôt que de supposer que l'opération a réussi :

<?php

if (!ftp_rename($ftp, '/public_html/oldname.txt', '/public_html/newname.txt')) {
    // Suppress the built-in warning and react to the failure yourself
    echo "Failed to rename file.\n";
}

ftp_close($ftp);

Causes d'échec courantes à vérifier :

• Source manquante — le chemin $from n'existe pas sur le serveur.
• Répertoire de travail incorrect — les chemins relatifs sont résolus par rapport au répertoire FTP courant ; utilisez ftp_chdir() ou des chemins absolus pour éviter les surprises.
• Permissions — l'utilisateur connecté ne dispose pas des droits d'écriture sur le répertoire.
• Cible existante — de nombreux serveurs refusent d'écraser un $to existant ; supprimez-le d'abord avec ftp_delete().

Résumé

ftp_rename() renomme — ou déplace — un fichier ou un répertoire sur un serveur FTP, retournant true en cas de succès et false en cas d'échec. Ouvrez la connexion avec ftp_connect(), authentifiez-vous avec ftp_login(), vérifiez la valeur de retour de chaque appel, et fermez la session avec ftp_close() une fois terminé.

Practice