Signatur
Beschreibung
ldap_set_option() ermöglicht die Konfiguration verschiedener LDAP-Verbindungsoptionen wie Protokollversion, Zeitlimits, Debugging-Einstellungen oder Referral-Verfolgung. Die Funktion wird in der Regel direkt nach dem Verbindungsaufbau mit ldap_connect() aufgerufen, noch bevor ein Bind-Vorgang stattfindet.
Der Parameter $ldap kann seit PHP 8.1 auch null sein, um eine globale Standardoption zu setzen, die für alle neu erstellten Verbindungen gilt. In PHP 5–8.0 muss eine gültige LDAP-Verbindungsressource übergeben werden.
Besonders wichtig ist die Option LDAP_OPT_PROTOCOL_VERSION, mit der das LDAP-Protokoll auf Version 3 umgestellt wird, was für viele moderne LDAP-Server (z. B. Active Directory, OpenLDAP) zwingend erforderlich ist. Weitere nützliche Optionen sind LDAP_OPT_TIMELIMIT, LDAP_OPT_NETWORK_TIMEOUT und LDAP_OPT_REFERRALS.
Nicht alle Optionen werden von jedem LDAP-Client-Bibliotheks-Backend unterstützt. Im Fehlerfall gibt die Funktion false zurück; es empfiehlt sich daher, den Rückgabewert zu prüfen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection|null | Eine LDAP-Verbindungsinstanz, die von ldap_connect() zurückgegeben wurde. Seit PHP 8.1 kann null übergeben werden, um die Option global zu setzen. |
|
| $option Pflicht | int | Die zu setzende Option als Ganzzahl-Konstante, z. B. LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_REFERRALS, LDAP_OPT_TIMELIMIT, LDAP_OPT_NETWORK_TIMEOUT oder LDAP_OPT_DEBUG_LEVEL. |
|
| $value Pflicht | array|int|string | Der neue Wert für die Option. Der erwartete Typ hängt von der jeweiligen Option ab: für LDAP_OPT_PROTOCOL_VERSION z. B. eine Ganzzahl (3), für LDAP_OPT_SERVER_CONTROLS ein Array von Steuerelementen. |
Rückgabewert
true zurück, wenn die Option erfolgreich gesetzt wurde, andernfalls false.Beispiele
LDAP-Protokollversion 3 und Referrals deaktivieren
<?php
$ldap = ldap_connect('ldap://ldap.example.com');
if ($ldap === false) {
die('Verbindung fehlgeschlagen.');
}
// LDAP-Protokoll Version 3 verwenden (für Active Directory erforderlich)
if (!ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3)) {
die('Protokollversion konnte nicht gesetzt werden.');
}
// Automatische Referral-Verfolgung deaktivieren
ldap_set_option($ldap, LDAP_OPT_REFERRALS, 0);
// Bind mit Benutzer
$bound = ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort');
if ($bound) {
echo 'Erfolgreich verbunden und authentifiziert.';
} else {
echo 'Bind fehlgeschlagen: ' . ldap_error($ldap);
}
ldap_unbind($ldap);Netzwerk-Timeout und TLS-Option setzen
<?php
$ldap = ldap_connect('ldap://ldap.example.com');
if ($ldap === false) {
die('Verbindung konnte nicht initialisiert werden.');
}
// Protokollversion auf 3 setzen
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
// Netzwerk-Timeout auf 10 Sekunden setzen
ldap_set_option($ldap, LDAP_OPT_NETWORK_TIMEOUT, 10);
// TLS starten (Start-TLS erfordert Protokollversion 3)
if (!ldap_start_tls($ldap)) {
die('TLS konnte nicht gestartet werden: ' . ldap_error($ldap));
}
echo 'TLS-Verbindung erfolgreich aufgebaut.';
ldap_unbind($ldap);// Wichtig · Fallstricke
Reihenfolge beachten: Optionen wie LDAP_OPT_PROTOCOL_VERSION müssen vor dem Aufruf von ldap_bind() gesetzt werden, da der Bind-Vorgang sonst mit der alten Einstellung ausgeführt wird.
TLS/SSL: Für verschlüsselte Verbindungen via ldap_start_tls() ist Protokollversion 3 zwingend erforderlich. Zertifikatsvalidierung kann über LDAP_OPT_X_TLS_REQUIRE_CERT gesteuert werden — das Deaktivieren (LDAP_OPT_X_TLS_NEVER) ist in Produktivumgebungen aus Sicherheitsgründen zu vermeiden.
Kompatibilität: Ab PHP 8.1 wurde die Ressource durch LDAP\Connection ersetzt. In älteren PHP-Versionen (5–8.0) wird eine Ressource vom Typ ldap link erwartet.