ftp_rename()

Die PHP-Funktion ftp_rename()

ftp_rename() benennt eine Datei oder ein Verzeichnis auf einem entfernten FTP-Server um. Da FTP keinen separaten „Verschieben"-Befehl kennt, dient diese Funktion auch dazu, eine Datei in ein anderes Verzeichnis zu verschieben — man gibt einfach einen neuen Pfad als Zielname an.

Diese Seite behandelt die Syntax, Parameter und den Rückgabewert, ein vollständiges Beispiel zum Verbinden, Umbenennen und Trennen, das Verschieben von Dateien mit demselben Aufruf sowie die Fehlerbehandlungsmuster, die für produktiven Code erforderlich sind.

Syntax

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

Vor PHP 8.1 war das erste Argument eine resource, die von ftp_connect() zurückgegeben wurde; seit PHP 8.1 ist es ein FTP\Connection-Objekt. Der Code ändert sich dabei nicht — die Variable stammt weiterhin direkt aus ftp_connect().

Parameter

Rückgabewert

Gibt bei Erfolg true und bei Misserfolg false zurück. Bei einem Fehler gibt PHP außerdem eine Warnung aus, die die Antwort des FTP-Servers beschreibt (zum Beispiel "550 oldname.txt: No such file or directory").

Ein vollständiges Beispiel

Vor dem Aufruf von ftp_rename() muss eine Verbindung geöffnet und eine Anmeldung durchgeführt werden. Die Verbindung aus ftp_connect() wird an ftp_login() und danach an jeden weiteren FTP-Aufruf übergeben:

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

Die Verbindung wird mit ftp_connect() hergestellt, die Anmeldung mit ftp_login() durchgeführt, die Datei mit ftp_rename() umbenannt und die Verbindung abschließend mit ftp_close() freigegeben. Das Prüfen des Rückgabewerts bei jedem Schritt verhindert, dass das Skript in einem fehlerhaften Zustand weiterläuft.

Eine Datei in ein anderes Verzeichnis verschieben

Da das zweite Argument ein vollständiger Pfad ist, verschiebt ftp_rename() die Datei in ein anderes Verzeichnis, wenn das Ziel in einem anderen Verzeichnis liegt, anstatt sie nur umzubenennen. Das Zielverzeichnis muss bereits existieren — erstellen Sie es bei Bedarf zuerst mit ftp_mkdir():

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

Fehlerbehandlung

ftp_rename() gibt false zurück (und erzeugt eine Warnung), wenn die Quelldatei nicht existiert, das Ziel bereits vorhanden ist oder keine ausreichenden Berechtigungen vorliegen. Prüfen Sie stets den Rückgabewert, anstatt Erfolg vorauszusetzen:

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

Häufige Fehlerursachen, auf die zu achten ist:

• Quelle nicht vorhanden — der $from-Pfad existiert nicht auf dem Server.
• Falsches Arbeitsverzeichnis — relative Pfade werden relativ zum aktuellen FTP-Verzeichnis aufgelöst; verwenden Sie ftp_chdir() oder absolute Pfade, um unerwartetes Verhalten zu vermeiden.
• Berechtigungen — der angemeldete Benutzer hat keinen Schreibzugriff auf das Verzeichnis.
• Ziel existiert bereits — viele Server verweigern das Überschreiben eines vorhandenen $to; löschen Sie es zuerst mit ftp_delete().

Zusammenfassung

ftp_rename() benennt eine Datei oder ein Verzeichnis auf einem FTP-Server um — oder verschiebt sie — und gibt bei Erfolg true und bei Misserfolg false zurück. Öffnen Sie die Verbindung mit ftp_connect(), authentifizieren Sie sich mit ftp_login(), prüfen Sie den Rückgabewert jedes Aufrufs und schließen Sie die Sitzung mit ftp_close() ab.

Übungen