rename()

Einführung

Die PHP-Funktion rename() benennt eine Datei oder ein Verzeichnis um — und da ein „Umbenennen" im Grunde nur eine Pfadänderung ist, kann dieselbe Funktion eine Datei oder ein Verzeichnis auch an einen anderen Ort verschieben. In PHP gibt es keine separate move()-Funktion; das Verschieben erfolgt durch Umbenennen zu einem neuen Pfad.

Diese Seite behandelt die Syntax und Parameter von rename(), wann die Funktion eingesetzt werden sollte (und wann nicht), häufige Fallstricke bei Berechtigungen und dateisystemübergreifenden Verschiebungen sowie vollständige, ausführbare Beispiele.

Syntax

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

Die Funktion gibt bei Erfolg true und bei einem Fehler false zurück. Im Fehlerfall wird außerdem eine E_WARNING ausgegeben.

Verhalten von rename()

Einige Regeln sind wichtig, bevor man sich auf rename() verlässt:

• Sie überschreibt. Wenn $to bereits existiert und eine reguläre Datei ist, überschreibt rename() sie (auf Unix-ähnlichen Systemen atomar). Prüfe vorher mit file_exists(), wenn du eine vorhandene Datei nicht überschreiben möchtest.
• Das Zielverzeichnis muss bereits existieren. rename() erstellt keine Zwischenordner. Verwende zuerst mkdir(), wenn das Zielverzeichnis fehlt.
• Berechtigungen sind entscheidend. Der PHP-Prozess (oft der Webserver-Benutzer, z. B. www-data) benötigt Schreibrechte sowohl im Quell- als auch im Zielverzeichnis — das Umbenennen ändert Verzeichniseinträge, nicht nur die Datei selbst.
• Dateisystemübergreifende Verschiebungen können fehlschlagen. Das Verschieben zwischen verschiedenen Einhängepunkten oder Laufwerken ist nicht auf jeder Plattform garantiert. Im Zweifelsfall die Datei mit copy() kopieren und anschließend das Original mit unlink() löschen.

Beispiele

Beispiel 1: Eine Datei umbenennen

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

Ausgabe:

File renamed successfully.

Hierdurch wird example.txt im selben Verzeichnis in new_example.txt umbenannt.

Beispiel 2: Eine Datei in ein anderes Verzeichnis verschieben

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

Ausgabe:

File moved successfully.

Da sich der Verzeichnisteil des Pfads geändert hat, wird die Datei in archive/ verschoben.

Beispiel 3: Sicheres Umbenennen mit Prüfungen

Im echten Code werden vor dem Umbenennen meist Validierungen durchgeführt, damit bei einem Fehler eine aussagekräftige Meldung ausgegeben wird und keine nichtssagende Warnung erscheint:

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

Dieses Beispiel schützt vor den drei häufigsten Ursachen, warum rename() fehlschlägt: eine fehlende Quelldatei, ein fehlendes Zielverzeichnis und unzureichende Berechtigungen.

rename() vs. copy()

Verwende rename(), wenn du Daten verschieben möchtest — der ursprüngliche Pfad verschwindet und es wird nichts dupliziert, was es auf demselben Dateisystem schnell und atomar macht. Verwende copy(), wenn das Original erhalten bleiben soll oder wenn das Verschieben über Dateisystemgrenzen hinweg nötig ist, wo rename() möglicherweise nicht funktioniert. Ein verbreitetes dateisystemübergreifendes Muster ist copy() gefolgt von unlink().

Verwandte Funktionen

• copy() — eine Datei duplizieren.
• unlink() — eine Datei löschen.
• file_exists() — prüfen, ob ein Pfad existiert, bevor er umbenannt wird.
• mkdir() — das Zielverzeichnis erstellen.
• is_dir() / is_file() — Dateien von Verzeichnissen unterscheiden.

Fazit

Die Funktion rename() benennt Dateien und Verzeichnisse in PHP um und verschiebt sie. Wichtig zu beachten: Sie überschreibt ein vorhandenes Ziel, erfordert, dass das Zielverzeichnis bereits existiert, benötigt Schreibrechte auf beiden Seiten und kann über Dateisystemgrenzen hinweg versagen. Validiere deine Pfade vorher und greife auf copy() + unlink() zurück, wenn ein einfaches Verschieben nicht möglich ist.

Übung