Signatur
Beschreibung
imap_listscan durchsucht den IMAP-Server nach Postfächern (Mailboxen), die sowohl dem $pattern (Muster) entsprechen als auch den angegebenen $content-String im Namen enthalten. Die Funktion ist damit eine Kombination aus Mustererkennung und Textsuche und eignet sich besonders, wenn aus einer großen Anzahl von Ordnern gezielt passende Postfächer herausgefiltert werden sollen.
Der Parameter $reference gibt den Ausgangspfad (oft den Servernamen) an, von dem aus gesucht wird. Das $pattern unterstützt Wildcards: * steht für beliebig viele Zeichen (auch über Hierarchieebenen hinweg), % entspricht beliebig vielen Zeichen innerhalb einer Ebene.
Die Funktion gibt ein Array mit den vollständigen Namen der gefundenen Postfächer zurück – oder false bei einem Fehler. Im Erfolgsfall, aber ohne Treffer, wird ein leeres Array zurückgegeben.
Diese Funktion ist sinnvoll in Szenarien, in denen dynamisch nach bestimmten Projektordnern, Kundenpostfächern oder thematischen Unterordnern gesucht werden muss, ohne alle Postfächer manuell zu durchsuchen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindungsinstanz, wie sie von imap_open() zurückgegeben wird. |
|
| $reference Pflicht | string | Der Ausgangspfad für die Suche, üblicherweise der Servername in geschweiften Klammern, z. B. {imap.example.com}. |
|
| $pattern Pflicht | string | Das Suchmuster mit optionalen Wildcards: * für beliebig viele Zeichen über alle Hierarchieebenen, % für beliebig viele Zeichen innerhalb einer Ebene. |
|
| $content Pflicht | string | Ein Teilstring, der im Namen der Postfächer enthalten sein muss. Nur Postfächer, die diesen Text im Namen tragen, werden zurückgegeben. |
Rückgabewert
false zurückgegeben. Werden keine passenden Postfächer gefunden, ist das Array leer.Beispiele
Alle Postfächer suchen, die 'Projekt' im Namen enthalten
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}', 'user@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Alle Postfächer der obersten Ebene durchsuchen, die 'Projekt' enthalten
$postfaecher = imap_listscan($imap, '{imap.example.com}', '%', 'Projekt');
if ($postfaecher === false) {
echo 'Fehler bei der Suche.';
} elseif (empty($postfaecher)) {
echo 'Keine passenden Postfächer gefunden.';
} else {
echo 'Gefundene Postfächer:' . PHP_EOL;
foreach ($postfaecher as $postfach) {
echo ' ' . $postfach . PHP_EOL;
}
}
imap_close($imap);Rekursive Suche in allen Unterordnern nach einem Stichwort
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}', 'user@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen.');
}
// Alle Postfächer inkl. Unterordner durchsuchen, die 'Archiv' im Namen haben
$treffer = imap_listscan($imap, '{imap.example.com}', '*', 'Archiv');
if (!empty($treffer)) {
echo count($treffer) . ' Archiv-Postfach/Archiv-Postfächer gefunden:' . PHP_EOL;
foreach ($treffer as $t) {
echo ' - ' . $t . PHP_EOL;
}
} else {
echo 'Kein Archiv-Postfach gefunden.';
}
imap_close($imap);// Wichtig · Fallstricke
Deprecation-Hinweis: Ab PHP 8.1.0 wurde der Ressourcentyp für IMAP-Verbindungen durch die Klasse IMAP\Connection ersetzt. In älteren PHP-Versionen (bis 8.0) war der Parameter vom Typ resource.
Serverkompatiblität: Die Verfügbarkeit und das Verhalten dieser Funktion hängen stark vom jeweiligen IMAP-Server ab. Nicht alle Server unterstützen die kombinierte Suche nach Muster und Inhalt gleichermaßen zuverlässig.
Encoding: Postfachnamen können in modifiziertem UTF-7 kodiert sein. Zum Dekodieren kann imap_utf7_decode() verwendet werden.
Alternativen: Für einfache Listenabfragen ohne Inhaltsfilter eignet sich imap_list() besser. Für detailliertere Informationen zu Postfächern sollte imap_getmailboxes() in Betracht gezogen werden.