ldap_parse_reference — Funktion · PHP-Referenz

Signatur

ldap_parse_reference(LDAP\Connection $ldap, LDAP\ResultEntry $entry, array &$referrals): bool

Beschreibung

ldap_parse_reference() wird verwendet, um aus einem LDAP-Ergebniseintrag, der eine Referenz (Referral) enthält, die enthaltenen Referenz-URIs zu extrahieren. LDAP-Referenzen werden von einem Server zurückgegeben, wenn er den Client an einen anderen Server oder Teilbaum weiterleiten möchte, der die gesuchten Einträge enthält.

Die extrahierten URIs werden als indexiertes Array in dem per Referenz übergebenen Parameter $referrals gespeichert. Jedes Element des Arrays enthält einen URI-String, der auf den referenzierten LDAP-Server oder Teilbaum zeigt.

Diese Funktion ist besonders nützlich in verteilten LDAP-Umgebungen, in denen Anfragen über mehrere Server verteilt sind. Mit ihr lässt sich prüfen, ob ein Ergebniseintrag eine Weiterleitung enthält, und die Zieladressen können für eine manuelle Weiterverarbeitung genutzt werden.

Typischerweise wird ldap_parse_reference() im Zusammenhang mit ldap_first_reference() und ldap_next_reference() eingesetzt, um alle Referenz-Einträge in einem LDAP-Ergebnis zu durchlaufen und auszuwerten.

Parameter

Name	Typ	Beschreibung
$ldap Pflicht	LDAP\Connection	Eine gültige LDAP-Verbindungsressource, die mit `ldap_connect()` erzeugt und mit `ldap_bind()` authentifiziert wurde.
$entry Pflicht	LDAP\ResultEntry	Ein LDAP-Ergebniseintrag vom Typ Referenz, typischerweise erhalten über `ldap_first_reference()` oder `ldap_next_reference()`.
$referrals Pflicht	array	Wird per Referenz übergeben und nach dem Aufruf mit einem indizierten Array von URI-Strings (Referenz-Adressen) befüllt, die im Eintrag enthalten sind.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Referenz erfolgreich geparst wurde, andernfalls false.

Beispiele

Alle Referenz-Einträge eines LDAP-Suchergebnisses auslesen

<?php
$ldap = ldap_connect('ldap://directory.example.com');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ldap, LDAP_OPT_REFERRALS, 0); // Manuelle Auflösung
ldap_bind($ldap);

$result = ldap_search($ldap, 'dc=example,dc=com', '(uid=jdoe)');

// Durch Referenz-Einträge iterieren
$ref = ldap_first_reference($ldap, $result);
while ($ref !== false) {
    $referrals = [];
    if (ldap_parse_reference($ldap, $ref, $referrals)) {
        echo "Gefundene Referenzen:" . PHP_EOL;
        foreach ($referrals as $uri) {
            echo "  -> " . $uri . PHP_EOL;
        }
    }
    $ref = ldap_next_reference($ldap, $ref);
}

ldap_unbind($ldap);
?>

Gefundene Referenzen: -> ldap://other.example.com/dc=other,dc=example,dc=com

Prüfen ob ein Eintrag Referenzen enthält und diese auswerten

<?php
$ldap = ldap_connect('ldap://directory.example.com');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ldap, LDAP_OPT_REFERRALS, 0);
ldap_bind($ldap);

$result = ldap_search($ldap, 'dc=example,dc=com', '(objectClass=*)');

$ref = ldap_first_reference($ldap, $result);
if ($ref === false) {
    echo "Keine Referenz-Einträge vorhanden." . PHP_EOL;
} else {
    $referrals = [];
    if (ldap_parse_reference($ldap, $ref, $referrals)) {
        echo "Anzahl der Referenzen: " . count($referrals) . PHP_EOL;
        foreach ($referrals as $index => $uri) {
            echo "Referenz " . ($index + 1) . ": " . $uri . PHP_EOL;
        }
    } else {
        echo "Fehler beim Parsen der Referenz." . PHP_EOL;
    }
}

ldap_unbind($ldap);
?>

Anzahl der Referenzen: 1 Referenz 1: ldap://other.example.com/ou=users,dc=other,dc=example,dc=com

// Wichtig · Fallstricke

Hinweis zur Option LDAP_OPT_REFERRALS: Standardmäßig folgt die PHP-LDAP-Erweiterung Referenzen automatisch. Um ldap_parse_reference() sinnvoll einzusetzen, sollte die automatische Referenzauflösung mit ldap_set_option($ldap, LDAP_OPT_REFERRALS, 0) deaktiviert werden, sodass Referenz-Einträge im Ergebnis erhalten bleiben.

Typen: Ab PHP 8.1 erwartet die Funktion Objekte vom Typ LDAP\Connection bzw. LDAP\ResultEntry statt der früher üblichen Ressourcen-Typen (resource). Älterer Code, der mit PHP < 8.1 entwickelt wurde, muss entsprechend angepasst werden.

Verfügbarkeit: Die Funktion setzt eine kompilierte PHP-LDAP-Erweiterung voraus (--with-ldap) und ist nicht in allen Standard-Distributionen aktiv.

Siehe auch

ldap_first_reference ldap_next_reference ldap_search ldap_parse_result ldap_set_option ldap_connect