rename()

Introduzione

La funzione PHP rename() rinomina un file o una directory — e poiché "rinominare" significa semplicemente cambiare un percorso, la stessa funzione sposta anche un file o una directory in una posizione diversa. In PHP non esiste una funzione separata move(); per spostare un elemento lo si rinomina con un nuovo percorso.

Questa pagina tratta la sintassi e i parametri di rename(), quando usarla (e quando no), le problematiche comuni legate ai permessi e agli spostamenti tra filesystem diversi, nonché esempi completi ed eseguibili.

Sintassi

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

La funzione restituisce true in caso di successo e false in caso di errore. In caso di errore emette anche un E_WARNING.

Come si comporta rename()

Vale la pena conoscere alcune regole prima di fare affidamento su rename():

• Sovrascrive. Se $to esiste già ed è un file normale, rename() lo sovrascrive (sui sistemi Unix-like, in modo atomico). Verificare prima con file_exists() se non si vuole sovrascrivere un file esistente.
• La directory di destinazione deve già esistere. rename() non crea cartelle intermedie. Usare prima mkdir() se la directory di destinazione manca.
• I permessi sono importanti. Il processo che esegue PHP (spesso l'utente del server web, ad es. www-data) necessita del permesso di scrittura sia sulla directory di origine sia su quella di destinazione — la rinomina modifica le voci di directory, non solo il file stesso.
• Gli spostamenti tra filesystem diversi possono fallire. Spostare elementi tra mount point o unità diverse non è garantito su tutte le piattaforme. In caso di dubbio, copiare il file con copy() e poi eliminare l'originale con unlink().

Esempi

Esempio 1: Rinominare un file

<?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.";
}

Output:

File renamed successfully.

Questo rinomina example.txt in new_example.txt nella stessa directory.

Esempio 2: Spostare un file in un'altra directory

<?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.";
}

Output:

File moved successfully.

Poiché la parte relativa alla directory del percorso è cambiata, il file viene spostato in archive/.

Esempio 3: Rinomina sicura con controlli

Nel codice reale è buona pratica validare prima di rinominare, così da fallire con un messaggio chiaro anziché con un avviso generico:

<?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).";
}

Questo protegge dalle tre cause più comuni di fallimento di rename(): sorgente mancante, directory di destinazione mancante e permessi insufficienti.

rename() vs. copy()

Usare rename() quando si vuole spostare i dati — il percorso originale scompare e nulla viene duplicato, rendendolo veloce e atomico sullo stesso filesystem. Usare copy() quando è necessario che l'originale rimanga in posizione, o quando bisogna spostare tra filesystem diversi dove rename() potrebbe non funzionare. Un pattern comune per filesystem incrociati è copy() seguito da unlink().

Funzioni correlate

• copy() — duplica un file.
• unlink() — elimina un file.
• file_exists() — verifica se un percorso esiste prima di rinominare.
• mkdir() — crea la directory di destinazione.
• is_dir() / is_file() — distingue file da directory.

Conclusione

La funzione rename() rinomina e sposta sia file che directory in PHP. Ricordare che sovrascrive una destinazione esistente, richiede che la directory di destinazione esista già, necessita di permessi di scrittura su entrambi i lati e potrebbe non funzionare tra filesystem diversi. Validare i percorsi prima dell'uso e ricorrere a copy() + unlink() quando uno spostamento diretto non è possibile.

Pratica