rename()

Introduction

La fonction PHP rename() renomme un fichier ou un répertoire — et parce qu'un « renommage » consiste simplement à changer un chemin, cette même fonction déplace également un fichier ou un répertoire vers un autre emplacement. Il n'existe pas de fonction move() séparée en PHP ; on déplace en renommant vers un nouveau chemin.

Cette page couvre la syntaxe et les paramètres de rename(), quand l'utiliser (et quand ne pas le faire), les pièges courants liés aux permissions et aux déplacements entre systèmes de fichiers, ainsi que des exemples complets exécutables.

Syntaxe

rename(string $from, string $to, ?resource $context = null): bool

La fonction retourne true en cas de succès et false en cas d'échec. En cas d'échec, elle émet également un E_WARNING.

Comportement de rename()

Quelques règles méritent d'être connues avant d'utiliser rename() :

• Elle écrase. Si $to existe déjà et est un fichier ordinaire, rename() l'écrase (sur les systèmes de type Unix, de manière atomique). Vérifiez d'abord avec file_exists() si vous ne souhaitez pas écraser un fichier existant.
• Le répertoire de destination doit déjà exister. rename() ne crée pas les dossiers intermédiaires. Utilisez mkdir() au préalable si le répertoire cible est manquant.
• Les permissions sont importantes. Le processus exécutant PHP (souvent l'utilisateur du serveur web, par ex. www-data) a besoin d'une permission d'écriture à la fois sur le répertoire source et sur le répertoire de destination — le renommage modifie les entrées de répertoire, pas seulement le fichier lui-même.
• Les déplacements entre systèmes de fichiers peuvent échouer. Le déplacement entre différents points de montage ou lecteurs n'est pas garanti sur toutes les plateformes. En cas de doute, utilisez copy() pour copier le fichier puis unlink() pour supprimer l'original.

Exemples

Exemple 1 : Renommer un fichier

<?php
// Create a file to work with so the example is self-contained.
file_put_contents('example.txt', 'hello');

if (rename('example.txt', 'new_example.txt')) {
    echo "File renamed successfully.";
} else {
    echo "Failed to rename the file.";
}

Résultat :

File renamed successfully.

Ceci renomme example.txt en new_example.txt dans le même répertoire.

Exemple 2 : Déplacer un fichier dans un autre répertoire

<?php
file_put_contents('example.txt', 'hello');

// Make sure the destination directory exists first.
if (!is_dir('archive')) {
    mkdir('archive');
}

if (rename('example.txt', 'archive/example.txt')) {
    echo "File moved successfully.";
} else {
    echo "Failed to move the file.";
}

Résultat :

File moved successfully.

La partie répertoire du chemin ayant changé, le fichier est déplacé dans archive/.

Exemple 3 : Renommage sécurisé avec vérifications

Dans du code réel, vous validez généralement avant de renommer afin d'échouer avec un message clair plutôt qu'un avertissement peu explicite :

<?php
$from = 'report.txt';
$to   = 'reports/2026-report.txt';

if (!file_exists($from)) {
    echo "Source file does not exist.";
} elseif (!is_dir(dirname($to))) {
    echo "Destination directory is missing.";
} elseif (rename($from, $to)) {
    echo "Done.";
} else {
    echo "Rename failed (check permissions).";
}

Ceci protège contre les trois raisons les plus courantes d'échec de rename() : une source manquante, un répertoire de destination manquant et des permissions insuffisantes.

rename() vs. copy()

Utilisez rename() lorsque vous souhaitez déplacer les données — le chemin d'origine disparaît et rien n'est dupliqué, ce qui le rend rapide et atomique sur le même système de fichiers. Utilisez copy() lorsque vous avez besoin que l'original reste en place, ou lorsque vous devez déplacer des données entre des systèmes de fichiers où rename() pourrait ne pas fonctionner. Un schéma courant pour les déplacements entre systèmes de fichiers consiste à utiliser copy() suivi de unlink().

Fonctions associées

• copy() — dupliquer un fichier.
• unlink() — supprimer un fichier.
• file_exists() — vérifier si un chemin existe avant de renommer.
• mkdir() — créer le répertoire de destination.
• is_dir() / is_file() — distinguer les fichiers des répertoires.

Conclusion

La fonction rename() renomme et déplace à la fois des fichiers et des répertoires en PHP. N'oubliez pas qu'elle écrase une destination existante, exige que le répertoire de destination existe déjà, nécessite des permissions d'écriture des deux côtés, et peut ne pas fonctionner entre systèmes de fichiers. Validez vos chemins au préalable, et utilisez copy() + unlink() lorsqu'un simple déplacement n'est pas possible.

Pratique