Signatur
Beschreibung
ldap_list durchsucht genau eine Ebene unterhalb des angegebenen Basis-DN (Base Distinguished Name). Im Gegensatz zu ldap_search (rekursive Suche über den gesamten Teilbaum) oder ldap_read (nur das Basisobjekt selbst) liefert ldap_list ausschließlich direkte Kinder des Basis-Eintrags – vergleichbar mit einem einfachen ls in einem Verzeichnis.
Diese Funktion ist besonders nützlich, wenn die Struktur des Verzeichnisses bekannt ist und man gezielt alle Einträge einer Organisationseinheit (OU) auflisten möchte, ohne tiefer verschachtelte Unterstrukturen zu durchsuchen. Das reduziert den Datenverkehr und die Serverlast erheblich.
Der Rückgabewert ist eine LDAP\Result-Ressource (seit PHP 8.1 ein Objekt), die mit Funktionen wie ldap_get_entries, ldap_first_entry oder ldap_count_entries weiterverarbeitet werden kann. Wird ein Array von LDAP-Verbindungen und/oder Basis-DNs übergeben, gibt die Funktion ein Array von Ergebnis-Ressourcen zurück.
Über die optionalen Parameter lassen sich die Ergebnismenge ($sizelimit), das Zeitlimit ($timelimit), die zurückgegebenen Attribute ($attributes) sowie das Dereferenzierungsverhalten ($deref) feingranular steuern. LDAP-Controls (z. B. für Paginierung) können seit PHP 7.3 über $controls übergeben werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection|array | Eine gültige LDAP-Verbindungsressource (seit PHP 8.1 ein LDAP\Connection-Objekt), die mit ldap_connect erzeugt und mit ldap_bind authentifiziert wurde. Alternativ ein Array von Verbindungen für parallele Suchen. |
|
| $base Pflicht | array|string | Der Basis-DN, unterhalb dessen gesucht wird, z. B. 'ou=Users,dc=example,dc=com'. Bei mehreren Verbindungen kann hier ein Array von Basis-DNs übergeben werden. |
|
| $filter Pflicht | array|string | LDAP-Suchfilter gemäß RFC 4515, z. B. '(objectClass=inetOrgPerson)'. Schränkt die zurückgegebenen Einträge auf passende Objekte ein. |
|
| $attributes | array | [] | Liste der zurückzugebenden Attribute, z. B. ['cn', 'mail', 'uid']. Ein leeres Array liefert alle Attribute des Eintrags zurück. |
| $attributes_only | int | 0 | Wenn auf 1 gesetzt, werden nur Attributnamen ohne deren Werte zurückgegeben. Nützlich, um die vorhandene Schema-Struktur zu ermitteln. |
| $sizelimit | int | -1 | Maximale Anzahl zurückzugebender Einträge. -1 bedeutet, dass das serverseitig konfigurierte Limit gilt. Ein clientseitiges Limit überschreibt nie das Serverlimit nach oben. |
| $timelimit | int | -1 | Maximale Wartezeit in Sekunden. -1 verwendet das serverseitige Standard-Timeout. Auch hier gilt: Das Serverlimit kann nicht clientseitig überschritten werden. |
| $deref | int | LDAP_DEREF_NEVER | Legt fest, wie Aliasse behandelt werden. Mögliche Werte: LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, LDAP_DEREF_ALWAYS. |
| $controls | array|null | null | Array von LDAP-Controls, die mit der Anfrage gesendet werden sollen (z. B. Server-Side Sorting oder Paginierung). Seit PHP 7.3 verfügbar. |
Rückgabewert
LDAP\Result-Instanz (vor PHP 8.1 eine Ressource), die mit ldap_get_entries o. ä. ausgewertet werden kann. Bei Übergabe von Arrays von Verbindungen wird ein Array von Ergebnisobjekten zurückgegeben. Im Fehlerfall wird false zurückgegeben.Beispiele
Alle Benutzer einer OU auflisten
<?php
$conn = ldap_connect('ldap://ldap.example.com');
ldap_set_option($conn, LDAP_OPT_PROTOCOL_VERSION, 3);
if (!ldap_bind($conn, 'cn=admin,dc=example,dc=com', 'geheim')) {
die('Bind fehlgeschlagen');
}
$base = 'ou=Users,dc=example,dc=com';
$filter = '(objectClass=inetOrgPerson)';
$attrs = ['cn', 'mail'];
$result = ldap_list($conn, $base, $filter, $attrs);
if ($result === false) {
die('Suche fehlgeschlagen: ' . ldap_error($conn));
}
$entries = ldap_get_entries($conn, $result);
echo 'Gefundene Einträge: ' . $entries['count'] . PHP_EOL;
for ($i = 0; $i < $entries['count']; $i++) {
$cn = $entries[$i]['cn'][0] ?? 'n/a';
$mail = $entries[$i]['mail'][0] ?? 'n/a';
echo "Name: $cn, E-Mail: $mail" . PHP_EOL;
}
ldap_unbind($conn);Suche mit Größenlimit und Fehlerbehandlung
<?php
$conn = ldap_connect('ldap://ldap.example.com');
ldap_set_option($conn, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($conn, 'cn=readonly,dc=example,dc=com', 'readonly123');
$base = 'ou=Groups,dc=example,dc=com';
$filter = '(objectClass=groupOfNames)';
$attrs = ['cn', 'member'];
$sizelimit = 10; // Maximal 10 Gruppen zurückgeben
$result = ldap_list($conn, $base, $filter, $attrs, 0, $sizelimit);
if ($result === false) {
echo 'Fehler: ' . ldap_error($conn) . PHP_EOL;
} else {
$anzahl = ldap_count_entries($conn, $result);
echo "Gefundene Gruppen (max. $sizelimit): $anzahl" . PHP_EOL;
$entry = ldap_first_entry($conn, $result);
while ($entry !== false) {
$attrs_entry = ldap_get_attributes($conn, $entry);
echo 'Gruppe: ' . ($attrs_entry['cn'][0] ?? 'unbekannt') . PHP_EOL;
$entry = ldap_next_entry($conn, $entry);
}
}
ldap_unbind($conn);// Wichtig · Fallstricke
Scope-Unterschied: ldap_list verwendet intern den Scope LDAP_SCOPE_ONELEVEL. Tiefere Unterknoten werden nicht durchsucht. Für eine rekursive Suche ist ldap_search zu verwenden, für die Abfrage eines einzelnen Objekts ldap_read.
Sicherheit: Nutzereingaben, die in den $filter-Parameter einfließen, müssen mit ldap_escape($input, '', LDAP_ESCAPE_FILTER) escaped werden, um LDAP-Injection-Angriffe zu verhindern.
Sizelimit: Das clientseitige $sizelimit kann das serverseitige Limit niemals erhöhen. Werden mehr Einträge angefordert als der Server zulässt, liefert ldap_errno den Fehlercode 4 (LDAP_SIZELIMIT_EXCEEDED). Paginierung über Server-Controls ist der empfohlene Weg für große Ergebnismengen.
PHP 8.1+: Verbindungs- und Ergebnis-Ressourcen wurden zu echten Objekten (LDAP\Connection und LDAP\Result) aufgewertet. Alter Code mit is_resource()-Prüfungen muss ggf. angepasst werden.