Signatur
Beschreibung
ftp_rename() sendet einen RNFR/RNTO-Befehl an den FTP-Server und benennt die unter $from angegebene Datei oder das Verzeichnis in $to um. Da dabei auch der Pfad geändert werden kann, lässt sich die Funktion gleichzeitig zum Verschieben von Dateien innerhalb des Servers verwenden.
Die Funktion arbeitet rein serverseitig – es werden keine Daten übertragen. Voraussetzung ist eine aktive FTP-Verbindung, die mit ftp_connect() und ftp_login() hergestellt wurde. Außerdem benötigt der angemeldete Benutzer auf dem Server ausreichende Schreibrechte für Quell- und Zielpfad.
Schlägt die Umbenennung fehl (z. B. weil die Quelldatei nicht existiert, das Ziel bereits vorhanden ist oder die Rechte fehlen), gibt die Funktion false zurück und löst eine PHP-Warnung aus. Im Erfolgsfall wird true zurückgegeben.
Für verschlüsselte Verbindungen kann statt ftp_connect() die Funktion ftp_ssl_connect() verwendet werden; ftp_rename() funktioniert mit beiden Verbindungstypen identisch.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ftp Pflicht | FTP\Connection | Eine aktive FTP-Verbindungsinstanz, wie sie von ftp_connect() oder ftp_ssl_connect() zurückgegeben wird. Vor PHP 8.1 war dies eine Ressource vom Typ resource. |
|
| $from Pflicht | string | Der aktuelle Pfad der Datei oder des Verzeichnisses auf dem FTP-Server, die umbenannt werden soll. Kann absolut (z. B. /var/www/datei.txt) oder relativ zum aktuellen Verzeichnis angegeben werden. |
|
| $to Pflicht | string | Der neue Pfad bzw. Name der Datei oder des Verzeichnisses auf dem FTP-Server. Enthält der Pfad ein anderes Verzeichnis als $from, wird die Datei effektiv verschoben. |
Rückgabewert
true zurück, wenn die Umbenennung erfolgreich war, andernfalls false. Im Fehlerfall wird zusätzlich eine PHP-Warnung ausgelöst.Beispiele
Einfaches Umbenennen einer Datei auf dem FTP-Server
<?php
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
die('Verbindung fehlgeschlagen');
}
if (!ftp_login($ftp, 'benutzer', 'geheim')) {
die('Anmeldung fehlgeschlagen');
}
$altName = '/public_html/bericht_alt.txt';
$neuName = '/public_html/bericht_2024.txt';
if (ftp_rename($ftp, $altName, $neuName)) {
echo 'Datei erfolgreich umbenannt.';
} else {
echo 'Umbenennung fehlgeschlagen.';
}
ftp_close($ftp);Datei in ein anderes Verzeichnis verschieben
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'benutzer', 'geheim');
// Datei von /uploads/ nach /archiv/ verschieben
$quelle = '/uploads/logo.png';
$ziel = '/archiv/logo.png';
if (ftp_rename($ftp, $quelle, $ziel)) {
echo 'Datei wurde erfolgreich verschoben.';
} else {
echo 'Verschieben fehlgeschlagen – prüfe Pfade und Berechtigungen.';
}
ftp_close($ftp);// Wichtig · Fallstricke
Rechte: Der FTP-Benutzer muss Schreibrechte sowohl im Quell- als auch im Zielverzeichnis besitzen. Fehlende Rechte führen zu einem FTP-Fehlercode (z. B. 550) und einem false-Rückgabewert.
Überschreiben: Viele FTP-Server erlauben kein Überschreiben einer bereits vorhandenen Zieldatei. In diesem Fall schlägt ftp_rename() fehl. Prüfe ggf. vorher mit ftp_nlist(), ob der Zielname bereits existiert.
PHP 8.1: Ab PHP 8.1 wird eine FTP\Connection-Objektinstanz erwartet; ältere Ressource-Werte sind nicht mehr kompatibel.
Fehlerbehandlung: Um die ausgelöste Warnung zu unterdrücken und selbst zu behandeln, kann dem Aufruf ein @-Operator vorangestellt oder ein eigener Fehler-Handler mit set_error_handler() registriert werden.