Signatur
Beschreibung
ldap_first_reference() extrahiert den ersten Referenz-Eintrag aus einem LDAP-Ergebnis-Objekt. LDAP-Referenzen (auch Referrals genannt) sind spezielle Einträge im Suchergebnis, die auf andere LDAP-Verzeichnisse oder Teilbäume verweisen. Sie unterscheiden sich von normalen Einträgen und werden mit eigenen Funktionen traversiert.
Diese Funktion ist der Einstiegspunkt für die Iteration über LDAP-Referenzen, analog zu ldap_first_entry() für normale Einträge. Mit ldap_next_reference() kann man anschließend die weiteren Referenzen abrufen.
Typischer Anwendungsfall ist das Auswerten von LDAP-Suchergebnissen in verteilten Verzeichnisumgebungen, bei denen der Server nicht alle Informationen selbst hält, sondern auf andere Server verweist. In solchen Umgebungen sollte man sowohl Einträge als auch Referenzen verarbeiten.
Gibt das zurückgegebene LDAP\ResultEntry-Objekt an ldap_parse_reference() weiter, um die eigentlichen Referral-URLs auszulesen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection | Eine aktive LDAP-Verbindungsressource, die mit ldap_connect() und anschließendem ldap_bind() erstellt wurde. |
|
| $result Pflicht | LDAP\Result | Das LDAP-Ergebnisobjekt, das von Suchfunktionen wie ldap_search(), ldap_list() oder ldap_read() zurückgegeben wurde. |
Rückgabewert
LDAP\ResultEntry-Objekt zurück, das die erste Referenz im Suchergebnis repräsentiert. Gibt false zurück, wenn keine Referenzen im Ergebnis vorhanden sind oder ein Fehler auftritt.Beispiele
Alle LDAP-Referenzen eines Suchergebnisses durchlaufen
<?php
$ldap = ldap_connect('ldap://verzeichnis.example.com');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort');
$result = ldap_search($ldap, 'dc=example,dc=com', '(objectClass=*)');
// Erste Referenz holen
$ref = ldap_first_reference($ldap, $result);
if ($ref === false) {
echo "Keine Referenzen im Ergebnis gefunden.\n";
} else {
do {
$referrals = [];
if (ldap_parse_reference($ldap, $ref, $referrals)) {
foreach ($referrals as $url) {
echo "Referral-URL: " . $url . "\n";
}
}
} while ($ref = ldap_next_reference($ldap, $ref));
}
ldap_unbind($ldap);Kombinierte Verarbeitung von Einträgen und Referenzen
<?php
$ldap = ldap_connect('ldap://verzeichnis.example.com');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort');
$result = ldap_search($ldap, 'dc=example,dc=com', '(objectClass=organizationalUnit)');
// Normale Einträge verarbeiten
$count = ldap_count_entries($ldap, $result);
echo "Gefundene Einträge: $count\n";
// Referenzen verarbeiten
$ref = ldap_first_reference($ldap, $result);
if ($ref !== false) {
$refCount = 0;
do {
$refCount++;
$referrals = [];
ldap_parse_reference($ldap, $ref, $referrals);
echo "Referenz $refCount verweist auf: " . implode(', ', $referrals) . "\n";
} while ($ref = ldap_next_reference($ldap, $ref));
} else {
echo "Keine Referenzen vorhanden.\n";
}
ldap_unbind($ldap);// Wichtig · Fallstricke
PHP-Versionen: Ab PHP 8.1 werden LDAP\Connection und LDAP\Result als eigene Klassen verwendet. In älteren PHP-Versionen (vor 8.1) waren dies einfache Ressourcen (resource).
LDAP_OPT_REFERRALS: Damit Referenzen überhaupt im Ergebnis erscheinen, muss die LDAP-Option LDAP_OPT_REFERRALS aktiviert sein (Standard ist 1/aktiviert). Wenn diese Option deaktiviert ist (ldap_set_option($ldap, LDAP_OPT_REFERRALS, 0)), verfolgt der Client keine Referrals und ldap_first_reference() wird stets false zurückgeben.
Verteilte Verzeichnisse: In produktiven Umgebungen mit verteilten LDAP-Verzeichnissen sollte man Referenzen immer auswerten, um vollständige Ergebnisse zu erhalten. Das Ignorieren von Referenzen kann zu unvollständigen Suchergebnissen führen.