Signatur
Beschreibung
imap_renamemailbox() ermöglicht das Umbenennen oder Verschieben eines Postfachs auf einem IMAP-Server. Der Quell- und Zielpfad werden als vollständige IMAP-Postfachbezeichnungen angegeben, also inklusive des Serverbezeichners in geschweiften Klammern, z. B. {imap.example.com}INBOX.Altordner.
Die Funktion wird typischerweise eingesetzt, um Unterordner in einer Mailbox-Struktur zu reorganisieren, beispielsweise beim Umbenennen von Archivordnern oder beim Verschieben von Unterpostfächern in andere Ordnerhierarchien. Sowohl der Quell- als auch der Zielpfad müssen denselben IMAP-Server referenzieren, da serverübergreifende Umbenennungen nicht unterstützt werden.
Zu beachten ist, dass einige IMAP-Server das Umbenennen des INBOX-Postfachs nicht erlauben und in diesem Fall einen Fehler zurückgeben. Es empfiehlt sich daher, den Rückgabewert stets zu prüfen und mögliche Fehler mit imap_last_error() auszuwerten.
Ab PHP 8.1 ist der erste Parameter ein IMAP\Connection-Objekt; in früheren Versionen war es eine Ressource vom Typ resource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindung, die zuvor mit imap_open() geöffnet wurde. |
|
| $from Pflicht | string | Der vollständige IMAP-Pfad des Quellpostfachs, z. B. {imap.example.com}INBOX.AlterName. |
|
| $to Pflicht | string | Der vollständige IMAP-Pfad des Zielpostfachs (neuer Name), z. B. {imap.example.com}INBOX.NeuerName. |
Rückgabewert
true zurück, wenn das Umbenennen erfolgreich war, andernfalls false. Im Fehlerfall kann imap_last_error() zur Fehlerdiagnose verwendet werden.Beispiele
Einen IMAP-Unterordner umbenennen
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}', 'benutzer@example.com', 'geheimesPasswort');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$server = '{imap.example.com:993/imap/ssl}';
$alterName = $server . 'INBOX.Archiv2022';
$neuerName = $server . 'INBOX.Archiv_2022';
if (imap_renamemailbox($imap, $alterName, $neuerName)) {
echo 'Postfach erfolgreich umbenannt.';
} else {
echo 'Fehler beim Umbenennen: ' . imap_last_error();
}
imap_close($imap);Ordner in eine andere Hierarchieebene verschieben
<?php
$server = '{imap.example.com:993/imap/ssl}';
$imap = imap_open($server, 'benutzer@example.com', 'geheimesPasswort');
if ($imap === false) {
die('Verbindung fehlgeschlagen.');
}
// Ordner 'INBOX.Temp.Wichtig' nach 'INBOX.Wichtig' verschieben
$quelle = $server . 'INBOX.Temp.Wichtig';
$ziel = $server . 'INBOX.Wichtig';
if (imap_renamemailbox($imap, $quelle, $ziel)) {
echo "Ordner erfolgreich verschoben.\n";
} else {
echo "Fehler: " . imap_last_error() . "\n";
}
imap_close($imap);// Wichtig · Fallstricke
Sicherheitshinweis: Werden Postfachpfade aus Benutzereingaben zusammengesetzt, muss eine sorgfältige Validierung und Bereinigung erfolgen, um Path-Traversal-Angriffe auf die Mailbox-Struktur zu verhindern. Nutzer könnten sonst versuchen, Systemordner umzubenennen oder auf unerlaubte Verzeichnisse zuzugreifen.
Kompatibilität: Ab PHP 8.1 erwartet die Funktion als ersten Parameter ein IMAP\Connection-Objekt statt einer resource. Älterer Code, der das Ergebnis von imap_open() als Ressource behandelt, muss ggf. angepasst werden.
INBOX: Das Umbenennen der INBOX selbst wird von den meisten IMAP-Servern abgelehnt. Nur Unterordner können zuverlässig umbenannt werden.
Die IMAP-Erweiterung ist standardmäßig nicht in PHP enthalten und muss bei der Kompilierung oder über eine Paketverwaltung aktiviert werden (php-imap).