Signatur
Beschreibung
imap_getsubscribed() ruft alle Postfächer ab, die der aktuelle Nutzer auf dem IMAP-Server abonniert hat und die dem angegebenen Referenzpfad sowie Suchmuster entsprechen. Abonnierte Mailboxen sind solche, die der Nutzer explizit mit imap_subscribe() markiert hat, um sie regelmäßig zu verfolgen.
Die Funktion ähnelt imap_getmailboxes(), listet jedoch ausschließlich abonnierte Postfächer auf. Sie gibt ein Array von Objekten zurück, wobei jedes Objekt die Eigenschaften name (vollständiger Name der Mailbox), delimiter (Trennzeichen in der Mailbox-Hierarchie) und attributes (Bit-Flags, z. B. LATT_NOINFERIORS) enthält.
Das $pattern-Argument erlaubt den Einsatz von Wildcards: * passt auf beliebig viele Zeichen (auch Hierarchietrenner), während % nur bis zum nächsten Hierarchietrenner passt. Mit dem Muster * werden alle abonnierten Postfächer unterhalb der Referenz zurückgeliefert.
Diese Funktion eignet sich besonders für E-Mail-Clients und Verwaltungsoberflächen, bei denen Nutzer eine persönliche Auswahl von Postfächern verwalten und nur diese angezeigt bekommen sollen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindung, die zuvor mit imap_open() geöffnet wurde. Ab PHP 8.1 ist dies ein IMAP\Connection-Objekt (zuvor eine Ressource). |
|
| $reference Pflicht | string | Der Basis-Referenzpfad, von dem aus gesucht wird, z. B. {imap.example.com}. Normalerweise wird hier der Server-String aus imap_open() verwendet. |
|
| $pattern Pflicht | string | Suchmuster für Postfächer. Wildcards: * steht für beliebige Zeichen inklusive Hierarchietrenner, % steht für beliebige Zeichen ohne Hierarchietrenner. Mit * werden alle abonnierten Mailboxen zurückgegeben. |
Rückgabewert
name (vollständiger Mailbox-Name), delimiter (Hierarchietrenner) und attributes (Bit-Flags) enthält. Gibt false zurück, wenn ein Fehler auftritt oder keine abonnierten Mailboxen gefunden wurden.Beispiele
Alle abonnierten Postfächer auflisten
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheimesPasswort');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$subscribed = imap_getsubscribed($imap, '{imap.example.com}', '*');
if ($subscribed === false || empty($subscribed)) {
echo 'Keine abonnierten Postfächer gefunden.' . PHP_EOL;
} else {
echo 'Abonnierte Postfächer:' . PHP_EOL;
foreach ($subscribed as $mailbox) {
echo ' - ' . $mailbox->name . PHP_EOL;
}
}
imap_close($imap);Nur abonnierte Unterordner eines bestimmten Ordners anzeigen
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheimesPasswort');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Nur direkte Unterordner von 'Projekte' (kein tieferes Nesting durch %)
$subscribed = imap_getsubscribed($imap, '{imap.example.com}', 'Projekte/%');
if (!empty($subscribed)) {
foreach ($subscribed as $mailbox) {
// Attribute prüfen: LATT_NOINFERIORS bedeutet, keine Unterordner möglich
$noChildren = ($mailbox->attributes & LATT_NOINFERIORS) ? 'Ja' : 'Nein';
printf("Mailbox: %-40s | Keine Unterordner: %s\n", $mailbox->name, $noChildren);
}
} else {
echo 'Keine passenden abonnierten Postfächer gefunden.' . PHP_EOL;
}
imap_close($imap);// Wichtig · Fallstricke
IMAP-Erweiterung erforderlich: Die Funktion ist nur verfügbar, wenn PHP mit der IMAP-Erweiterung (--with-imap) kompiliert wurde. Viele moderne Hosting-Umgebungen binden diese optional ein.
Änderung in PHP 8.1: Der erste Parameter ist nun vom Typ IMAP\Connection und kein resource mehr. Älterer Code, der den Rückgabewert von imap_open() als Ressource behandelt, muss ggf. angepasst werden.
Unterschied zu imap_getmailboxes(): imap_getsubscribed() liefert nur explizit abonnierte Postfächer, während imap_getmailboxes() alle vorhandenen Postfächer zurückgibt. Das Abonnement wird serverseitig gespeichert und ist nutzerspezifisch.
Sicherheit: Benutzereingaben, die in $reference oder $pattern einfließen, sollten sorgfältig validiert und bereinigt werden, um IMAP-Injection-Angriffe zu verhindern.