Signatur
Beschreibung
imap_lsub() fragt den IMAP-Server nach allen Postfächern ab, die der aktuelle Benutzer abonniert hat und die dem angegebenen Muster entsprechen. Dies entspricht dem IMAP-Befehl LSUB (List Subscribed). Im Gegensatz zu imap_list(), das alle vorhandenen Postfächer auflistet, liefert diese Funktion nur die abonnierten Mailboxen.
Der Parameter $reference gibt den Basis-Pfad auf dem Server an (häufig ein leerer String oder ein Namespace wie {imap.example.com}), während $pattern einen Platzhalter enthält. Das Zeichen * steht dabei für alle Ebenen, % nur für die aktuelle Ebene der Ordnerhierarchie.
Diese Funktion eignet sich besonders, wenn man eine E-Mail-Anwendung baut, bei der Benutzer ihre Ordner abonnieren können (z. B. bei NNTP oder IMAP-Servern mit vielen Ordnern), und nur die relevanten abonnierten Ordner anzeigen möchte.
Hinweis: Ab PHP 8.1.0 wird der erste Parameter als IMAP\Connection-Objekt erwartet. Frühere Versionen verwenden eine Ressource vom Typ resource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine IMAP-Verbindung, wie sie von imap_open() zurückgegeben wird. Ab PHP 8.1.0 muss dies ein IMAP\Connection-Objekt sein. |
|
| $reference Pflicht | string | Der Referenz-Pfad, normalerweise die Server-Spezifikation in der Form {hostname} oder ein leerer String, um den aktuellen Kontext zu verwenden. |
|
| $pattern Pflicht | string | Suchmuster für Postfächer. * passt auf alle Ebenen der Ordnerhierarchie, % nur auf die aktuelle Ebene. Beispiel: * für alle abonnierten Ordner oder INBOX.* für alle Unterordner von INBOX. |
Rückgabewert
{imap.example.com}INBOX. Bei einem Fehler wird false zurückgegeben.Beispiele
Alle abonnierten Postfächer auflisten
<?php
$imap = imap_open(
'{imap.example.com:993/imap/ssl}',
'benutzer@example.com',
'geheimesPasswort'
);
if (!$imap) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$abonniert = imap_lsub($imap, '{imap.example.com}', '*');
if ($abonniert === false) {
echo 'Fehler beim Abrufen der Postfächer.';
} else {
echo 'Abonnierte Postfächer:' . PHP_EOL;
foreach ($abonniert as $postfach) {
echo ' ' . $postfach . PHP_EOL;
}
}
imap_close($imap);Nur abonnierte Unterordner von INBOX anzeigen
<?php
$imap = imap_open(
'{imap.example.com:993/imap/ssl}',
'benutzer@example.com',
'geheimesPasswort'
);
if (!$imap) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Nur direkte Unterordner von INBOX (keine tiefere Hierarchie durch %)
$unterordner = imap_lsub($imap, '{imap.example.com}', 'INBOX.%');
if ($unterordner === false || empty($unterordner)) {
echo 'Keine abonnierten Unterordner gefunden.';
} else {
echo 'Abonnierte INBOX-Unterordner:' . PHP_EOL;
foreach ($unterordner as $ordner) {
// Nur den Ordnernamen ohne Server-Präfix anzeigen
$name = preg_replace('/^\{[^}]+\}/', '', $ordner);
echo ' ' . $name . PHP_EOL;
}
}
imap_close($imap);// Wichtig · Fallstricke
Erweiterung erforderlich: Diese Funktion setzt die PHP-Erweiterung ext-imap voraus, die separat kompiliert oder installiert werden muss. Seit PHP 8.4 ist ext-imap als deprecated markiert und wird in einer zukünftigen Version entfernt. Für neue Projekte sollten Alternativen wie ddeboer/imap oder die Verwendung von php-imap via Composer in Betracht gezogen werden.
Unterschied zu imap_list(): Während imap_list() alle auf dem Server vorhandenen Postfächer auflistet, liefert imap_lsub() nur die abonnierten Postfächer. Bei Servern mit sehr vielen Ordnern (z. B. in Unternehmensumgebungen) kann imap_lsub() deutlich effizienter sein.
Zeichenkodierung: Postfachnamen mit Sonderzeichen werden vom Server häufig in modifiziertem UTF-7 kodiert zurückgegeben. Zur lesbaren Anzeige sollte imap_utf7_decode() verwendet werden.