Signatur
Beschreibung
ldap_read() ist die PHP-Funktion für LDAP-Suchen mit dem Scope LDAP_SCOPE_BASE. Das bedeutet, dass nur der direkt angegebene Basis-DN (Base-DN) ausgelesen wird – weder untergeordnete noch übergeordnete Einträge werden in die Suche einbezogen. Damit eignet sich die Funktion ideal, um einen einzelnen, bereits bekannten LDAP-Eintrag gezielt abzurufen.
Im Gegensatz zu ldap_search() (Scope: subtree) und ldap_list() (Scope: one) durchsucht ldap_read() ausschließlich den angegebenen Knoten selbst. Das macht sie effizienter, wenn lediglich die Attribute eines bekannten Objekts – z. B. eines Benutzers oder einer Gruppe – gelesen werden sollen.
Das zurückgegebene Result-Handle kann anschließend mit ldap_get_entries(), ldap_first_entry() oder ldap_get_attributes() weiterverarbeitet werden. Wird ein Array von LDAP-Verbindungen übergeben, arbeitet die Funktion parallel auf mehreren Verzeichnissen und gibt ein Array von Ergebnis-Handles zurück.
Ab PHP 8.1.0 werden LDAP-Verbindungen als Objekte vom Typ LDAP\Connection repräsentiert; zuvor waren es Ressourcen vom Typ resource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection|array | Eine gültige LDAP-Verbindung, die mit ldap_connect() erstellt und mit ldap_bind() authentifiziert wurde. Alternativ ein Array solcher Verbindungen für parallele Abfragen. |
|
| $base Pflicht | array|string | Der Distinguished Name (DN) des Eintrags, der gelesen werden soll, z. B. "uid=max,ou=users,dc=example,dc=com". Bei einem Array von Verbindungen muss hier ebenfalls ein Array mit den entsprechenden Base-DNs angegeben werden. |
|
| $filter Pflicht | array|string | LDAP-Suchfilter gemäß RFC 4515, z. B. "(objectClass=*)". Da nur ein Eintrag gelesen wird, reicht oft der Catch-all-Filter. Bei mehreren Verbindungen kann ein Array von Filtern übergeben werden. |
|
| $attributes | array | [] | Array der zurückzugebenden Attributnamen, z. B. ["cn", "mail", "telephoneNumber"]. Ein leeres Array bedeutet, dass alle Attribute zurückgegeben werden. |
| $attributes_only | int | 0 | Wird auf 1 gesetzt, werden nur die Attributnamen ohne deren Werte zurückgegeben. Standard ist 0 (Attribute mit Werten). |
| $sizelimit | int | -1 | Maximale Anzahl zurückzugebender Einträge. -1 bedeutet, dass das serverseitige Limit gilt. Da ldap_read() ohnehin nur einen Eintrag liest, ist dieser Parameter hier meist irrelevant. |
| $timelimit | int | -1 | Maximale Ausführungszeit der Suche in Sekunden. -1 verwendet das serverseitige Limit. |
| $deref | int | LDAP_DEREF_NEVER | Legt fest, wie Aliase behandelt werden. Mögliche Werte: LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, LDAP_DEREF_ALWAYS. |
| $controls | array|null | null | Array von LDAP-Steuerelementen (Server Controls), die mit der Anfrage gesendet werden sollen. null sendet keine zusätzlichen Controls. |
Rückgabewert
LDAP\Result-Objekt (vor PHP 8.1 eine Ressource), das mit den LDAP-Ergebnis-Funktionen weiterverarbeitet werden kann. Bei mehreren Verbindungen (Array) wird ein Array von Ergebnis-Objekten zurückgegeben. Im Fehlerfall wird false zurückgegeben.Beispiele
Einzelnen LDAP-Benutzer anhand bekannter DN lesen
<?php
$ldap = ldap_connect('ldap://ldap.example.com');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
if (!ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort')) {
die('Bind fehlgeschlagen');
}
$dn = 'uid=max.mustermann,ou=users,dc=example,dc=com';
$filter = '(objectClass=*)';
$attrs = ['cn', 'mail', 'telephoneNumber'];
$result = ldap_read($ldap, $dn, $filter, $attrs);
if ($result === false) {
die('Lesen fehlgeschlagen: ' . ldap_error($ldap));
}
$entries = ldap_get_entries($ldap, $result);
if ($entries['count'] > 0) {
$user = $entries[0];
echo 'Name: ' . ($user['cn'][0] ?? '-') . PHP_EOL;
echo 'E-Mail: ' . ($user['mail'][0] ?? '-') . PHP_EOL;
echo 'Telefon: ' . ($user['telephonenumber'][0] ?? '-') . PHP_EOL;
}
ldap_unbind($ldap);Nur Attributnamen eines Eintrags ermitteln (ohne Werte)
<?php
$ldap = ldap_connect('ldap://ldap.example.com');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort');
$dn = 'uid=max.mustermann,ou=users,dc=example,dc=com';
$result = ldap_read($ldap, $dn, '(objectClass=*)', [], 1); // attributes_only = 1
if ($result !== false) {
$entry = ldap_first_entry($ldap, $result);
$attrs = ldap_get_attributes($ldap, $entry);
echo 'Vorhandene Attribute:' . PHP_EOL;
for ($i = 0; $i < $attrs['count']; $i++) {
echo ' - ' . $attrs[$i] . PHP_EOL;
}
}
ldap_unbind($ldap);// Wichtig · Fallstricke
Sicherheitshinweis: LDAP-DNs und Filterwerte, die aus Benutzereingaben stammen, müssen vor der Verwendung mit ldap_escape() bereinigt werden, um LDAP-Injection-Angriffe zu verhindern. Für DNs ist der Flag LDAP_ESCAPE_DN, für Filterwerte LDAP_ESCAPE_FILTER zu verwenden.
Scope-Unterschied: ldap_read() durchsucht ausschließlich den angegebenen DN selbst (Scope base). Für die Suche in einer Ebene unterhalb des Base-DN ist ldap_list() (Scope one), für die rekursive Suche ldap_search() (Scope subtree) zu verwenden.
PHP 8.1+: LDAP-Verbindungen und -Ergebnisse sind nun echte Objekte der Klassen LDAP\Connection und LDAP\Result. Alte is_resource()-Prüfungen funktionieren nicht mehr; stattdessen instanceof oder direkte Vergleiche mit false verwenden.