Signatur
Beschreibung
ssh2_sftp_rename() benennt eine entfernte Datei oder ein Verzeichnis über eine aktive SFTP-Verbindung um. Die Funktion kann auch verwendet werden, um Dateien innerhalb des Dateisystems des entfernten Servers zu verschieben, sofern Quell- und Zielpfad auf demselben Dateisystem liegen.
Für die Verwendung wird zunächst eine SSH2-Verbindung mit ssh2_connect() benötigt, aus der anschließend mit ssh2_sftp() eine SFTP-Ressource erzeugt wird. Diese SFTP-Ressource wird als erster Parameter an ssh2_sftp_rename() übergeben.
Die Pfadangaben für $from und $to müssen absolute Pfade auf dem entfernten System sein. Relative Pfade können zu unerwarteten Ergebnissen führen, da sie relativ zum Arbeitsverzeichnis des SFTP-Subsystems interpretiert werden. Es empfiehlt sich, immer mit vollständigen absoluten Pfaden zu arbeiten.
Die Funktion ist Teil der SSH2-Erweiterung (PECL ssh2) und steht nicht im PHP-Kern zur Verfügung. Sie muss separat installiert werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $sftp Pflicht | resource | Eine SFTP-Ressource, die mit ssh2_sftp() aus einer bestehenden SSH2-Verbindung erzeugt wurde. |
|
| $from Pflicht | string | Der absolute Pfad zur Quelldatei oder zum Quellverzeichnis auf dem entfernten Server. | |
| $to Pflicht | string | Der absolute Zielpfad, zu dem die Datei oder das Verzeichnis auf dem entfernten Server umbenannt bzw. verschoben werden soll. |
Rückgabewert
true zurück, wenn die Umbenennung erfolgreich war, andernfalls false. Ein Fehler tritt beispielsweise auf, wenn die Quelldatei nicht existiert, der Benutzer keine ausreichenden Berechtigungen hat oder der Zielpfad bereits belegt ist.Beispiele
Datei auf entferntem Server umbenennen
<?php
// SSH2-Verbindung aufbauen
$connection = ssh2_connect('sftp.example.com', 22);
if (!$connection) {
die('Verbindung fehlgeschlagen.');
}
// Authentifizierung mit Benutzername und Passwort
ssh2_auth_password($connection, 'benutzername', 'geheimesPasswort');
// SFTP-Subsystem initialisieren
$sftp = ssh2_sftp($connection);
if (!$sftp) {
die('SFTP-Initialisierung fehlgeschlagen.');
}
// Datei umbenennen
$ergebnis = ssh2_sftp_rename($sftp, '/var/www/html/alt.txt', '/var/www/html/neu.txt');
if ($ergebnis) {
echo 'Datei erfolgreich umbenannt.';
} else {
echo 'Umbenennung fehlgeschlagen.';
}Datei in ein anderes Verzeichnis auf dem Server verschieben
<?php
$connection = ssh2_connect('sftp.example.com', 22);
ssh2_auth_password($connection, 'benutzername', 'geheimesPasswort');
$sftp = ssh2_sftp($connection);
// Datei in ein Archiv-Verzeichnis verschieben
$quellpfad = '/var/www/html/uploads/bericht_2024.pdf';
$zielpfad = '/var/www/html/archiv/bericht_2024.pdf';
if (ssh2_sftp_rename($sftp, $quellpfad, $zielpfad)) {
echo 'Datei wurde erfolgreich ins Archiv verschoben.';
} else {
echo 'Verschieben fehlgeschlagen. Prüfen Sie Pfade und Berechtigungen.';
}// Wichtig · Fallstricke
Erweiterung erforderlich: ssh2_sftp_rename() ist Teil der PECL-Erweiterung ssh2 und muss separat installiert werden (pecl install ssh2). Sie ist nicht im PHP-Standard-Lieferumfang enthalten.
Berechtigungen: Die Operation schlägt fehl, wenn der auf dem SSH-Server angemeldete Benutzer keine Schreibrechte im Zielverzeichnis oder keine Leserechte auf die Quelldatei besitzt.
Zielpfad existiert bereits: Falls am Zielpfad bereits eine Datei existiert, hängt das Verhalten vom SFTP-Server ab. Auf vielen Systemen wird die vorhandene Datei überschrieben, auf anderen schlägt die Operation fehl. Es empfiehlt sich, vor der Umbenennung mit ssh2_sftp_stat() zu prüfen, ob der Zielpfad bereits belegt ist.
Sicherheitshinweis: Pfade, die aus Benutzereingaben stammen, sollten sorgfältig validiert und bereinigt werden, um Path-Traversal-Angriffe (z. B. mit /../) zu verhindern.