ftp_rename()

La funzione PHP ftp_rename()

ftp_rename() rinomina un file o una directory su un server FTP remoto. Poiché FTP non dispone di un comando "sposta" separato, questa stessa funzione è anche il modo per spostare un file in una directory diversa — è sufficiente fornire un nuovo percorso come nome di destinazione.

Questa pagina tratta la sintassi, i parametri e il valore restituito, un esempio completo di connessione-rinomina-disconnessione, come spostare file con la stessa chiamata e i pattern di gestione degli errori necessari per il codice in produzione.

Sintassi

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

Prima di PHP 8.1 il primo argomento era una resource restituita da ftp_connect(); da PHP 8.1 è un oggetto FTP\Connection. Il codice non cambia — la variabile proviene direttamente da ftp_connect().

Parametri

Valore restituito

Restituisce true in caso di successo e false in caso di errore. In caso di errore, PHP emette anche un avviso che descrive la risposta del server FTP (ad esempio, "550 oldname.txt: No such file or directory").

Un esempio completo

È necessario aprire una connessione ed effettuare il login prima di chiamare ftp_rename(). La connessione ottenuta da ftp_connect() viene passata a ftp_login() e poi a ogni successiva chiamata FTP:

<?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);

Ci connettiamo con ftp_connect(), ci autentichiamo con ftp_login(), rinominiamo con ftp_rename() e infine rilasciamo la connessione con ftp_close(). Verificare il valore restituito di ogni passaggio impedisce allo script di continuare in uno stato non valido.

Spostare un file in un'altra directory

Poiché il secondo argomento è un percorso completo, fornire a ftp_rename() una destinazione in una directory diversa sposta il file invece di semplicemente rinominarlo. La directory di destinazione deve già esistere — crearla prima con ftp_mkdir() se necessario:

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

Gestione degli errori

ftp_rename() restituisce false (e genera un avviso) quando il sorgente non esiste, la destinazione esiste già o si mancano i permessi. Verificare sempre il valore restituito invece di presumere il successo:

<?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);

Cause comuni di errore da verificare:

• Sorgente mancante — il percorso $from non esiste sul server.
• Directory di lavoro errata — i percorsi relativi si risolvono rispetto alla directory FTP corrente; usare ftp_chdir() o percorsi assoluti per evitare sorprese.
• Permessi — l'utente autenticato non ha accesso in scrittura alla directory.
• Destinazione esistente — molti server rifiutano di sovrascrivere un $to esistente; eliminarlo prima con ftp_delete().

Riepilogo

ftp_rename() rinomina — o sposta — un file o una directory su un server FTP, restituendo true in caso di successo e false in caso di errore. Aprire la connessione con ftp_connect(), autenticarsi con ftp_login(), verificare il valore restituito di ogni chiamata e chiudere la sessione con ftp_close() al termine.

Esercizio