Signatur
Beschreibung
ldap_exop_refresh ist eine Hilfsfunktion für die erweiterte LDAP-Operation Refresh gemäß RFC 2589. Sie dient dazu, einen dynamischen LDAP-Eintrag am Leben zu erhalten, indem dessen Time-to-Live (TTL) erneuert wird. Dynamische Einträge besitzen eine begrenzte Lebensdauer und werden vom Server automatisch gelöscht, wenn sie nicht rechtzeitig aktualisiert werden.
Die Funktion sendet eine LDAP_EXOP_REFRESH-Anfrage an den verbundenen LDAP-Server. Als Antwort übermittelt der Server die tatsächlich gewährte neue TTL, die unter Umständen von der angeforderten $ttl abweichen kann. Der tatsächliche Wert wird in $refreshed_ttl gespeichert, sofern dieser Parameter übergeben wird.
Typische Einsatzgebiete sind Präsenz-Dienste, dynamische Einträge für Online-Benutzer oder temporäre Ressourcen in einem LDAP-Verzeichnis, die regelmäßig aktualisiert werden müssen. Die Funktion setzt eine aktive LDAP-Verbindung (LDAP\Connection) voraus, die z. B. mit ldap_connect und ldap_bind hergestellt wurde.
Wird $refreshed_ttl als Referenzparameter übergeben, enthält er nach dem Aufruf die vom Server bestätigte Restlaufzeit in Sekunden. Ohne diesen Parameter gibt die Funktion bei Erfolg den bestätigten TTL-Wert direkt als Integer zurück.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection | Eine gültige LDAP-Verbindungsressource, die mit ldap_connect erstellt und mit ldap_bind authentifiziert wurde. |
|
| $dn Pflicht | string | Der Distinguished Name (DN) des dynamischen LDAP-Eintrags, dessen TTL verlängert werden soll, z. B. 'uid=jdoe,ou=people,dc=example,dc=com'. |
|
| $ttl Pflicht | int | Die gewünschte neue Gültigkeitsdauer des Eintrags in Sekunden. Der Server kann einen abweichenden Wert gewähren. | |
| $refreshed_ttl | int | null | Wenn angegeben, wird dieser Referenzparameter nach dem Aufruf mit der vom Server tatsächlich bestätigten TTL in Sekunden befüllt. |
Rückgabewert
int zurück, wenn $refreshed_ttl nicht übergeben wurde. Wird $refreshed_ttl als Referenz übergeben, gibt die Funktion true bei Erfolg zurück. Im Fehlerfall wird false zurückgegeben.Beispiele
Dynamischen LDAP-Eintrag per Refresh am Leben erhalten
<?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', 'geheimes_passwort');
$dn = 'uid=dynamicuser,ou=dynamic,dc=example,dc=com';
$ttl = 3600; // 1 Stunde gewünscht
$result = ldap_exop_refresh($ldap, $dn, $ttl, $refreshed_ttl);
if ($result !== false) {
echo "Eintrag aktualisiert. Tatsächliche TTL: " . $refreshed_ttl . " Sekunden.\n";
} else {
echo "Refresh fehlgeschlagen.\n";
}
ldap_unbind($ldap);
?>Regelmäßiges Auffrischen in einer Schleife
<?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', 'geheimes_passwort');
$dn = 'uid=onlineuser,ou=presence,dc=example,dc=com';
$ttl = 300; // 5 Minuten
// Simulierter Keep-Alive-Loop (in Praxis z. B. per Cron oder Hintergrundprozess)
for ($i = 0; $i < 3; $i++) {
$confirmedTtl = ldap_exop_refresh($ldap, $dn, $ttl);
if ($confirmedTtl === false) {
echo "Fehler beim Refresh in Iteration " . ($i + 1) . "\n";
break;
}
echo "Iteration " . ($i + 1) . ": TTL bestätigt mit " . $confirmedTtl . " Sekunden.\n";
sleep(1); // In Realität: sleep($confirmedTtl - 30) o. Ä.
}
ldap_unbind($ldap);
?>// Wichtig · Fallstricke
Serverunterstützung prüfen: Nicht alle LDAP-Server unterstützen die Refresh-Extended-Operation gemäß RFC 2589. Vor dem Einsatz sollte geprüft werden, ob der Server die OID 1.3.6.1.4.1.1466.101.119.1 in seinen Root-DSE-Supported-Extensions listet.
PHP-Version: Die Funktion ist seit PHP 7.3.0 verfügbar. Ab PHP 8.1.0 erwartet der erste Parameter ein LDAP\Connection-Objekt statt einer veralteten Ressource.
Fehlerbehandlung: Im Fehlerfall gibt die Funktion false zurück. Detaillierte Fehlermeldungen können mit ldap_error oder ldap_errno abgerufen werden.