Signatur
Beschreibung
ldap_rename_ext funktioniert analog zu ldap_rename, gibt jedoch anstelle eines booleschen Wertes ein LDAP\Result-Objekt zurück. Damit lässt sich die Operation asynchron auswerten, z. B. durch anschließendes Übergeben des Ergebnisses an ldap_parse_result, um Serversteuerungen (Controls) und Fehlercodes auszulesen.
Mit dieser Funktion kann der relative Distinguished Name (RDN) eines LDAP-Eintrags geändert werden, optional verbunden mit einem Umzug in einen anderen Zweig des Verzeichnisbaums (neuer übergeordneter DN). Der Parameter delete_old_rdn steuert, ob der bisherige RDN-Wert als Attribut im Eintrag erhalten bleibt oder gelöscht wird.
Der Einsatz von LDAP-Controls über den Parameter controls ermöglicht es, serverseitige Erweiterungen zu nutzen, z. B. das Mitführen einer Tree-Delete- oder Pre-Read-Control. Das zurückgegebene LDAP\Result-Objekt kann anschließend mit ldap_parse_result analysiert werden, um Serverantworten inklusive enthaltener Controls auszuwerten.
Diese Funktion ist besonders nützlich in Szenarien, in denen eine feinere Kontrolle über die LDAP-Serverantwort erforderlich ist oder wenn Controls verwendet werden sollen, die über den einfachen Erfolg/Fehler-Status hinausgehen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection | Eine gültige LDAP-Verbindungsressource, die zuvor mit ldap_connect und ldap_bind erstellt wurde. |
|
| $dn Pflicht | string | Der Distinguished Name (DN) des Eintrags, der umbenannt werden soll, z. B. cn=Max Mustermann,ou=Users,dc=example,dc=com. |
|
| $new_rdn Pflicht | string | Der neue relative Distinguished Name (RDN) des Eintrags, z. B. cn=Max Muster. |
|
| $new_parent Pflicht | string | Der DN des neuen übergeordneten Eintrags. Soll der Eintrag im selben Zweig bleiben, wird der aktuelle übergeordnete DN angegeben. Ein leerer String bewirkt, dass der übergeordnete Knoten unverändert bleibt. | |
| $delete_old_rdn Pflicht | bool | Wenn true, wird der alte RDN-Wert aus dem Eintrag gelöscht. Bei false bleibt der alte Wert als zusätzliches Attribut erhalten. |
|
| $controls | array|null | null | Ein optionales Array mit LDAP-Controls, die mit der Anfrage an den Server gesendet werden sollen. Jedes Control-Element ist ein assoziatives Array mit den Schlüsseln oid, iscritical und optional value. |
Rückgabewert
LDAP\Result-Objekt zurück, das mit ldap_parse_result weiterverarbeitet werden kann. Im Fehlerfall wird false zurückgegeben.Beispiele
Eintrag umbenennen und Ergebnis auswerten
<?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 = 'cn=Max Mustermann,ou=Users,dc=example,dc=com';
$newRdn = 'cn=Max Muster';
$newParent = 'ou=Users,dc=example,dc=com';
$result = ldap_rename_ext($ldap, $dn, $newRdn, $newParent, true);
if ($result === false) {
echo 'Fehler beim Senden der Umbenennung: ' . ldap_error($ldap);
} else {
ldap_parse_result($ldap, $result, $errcode, $matcheddn, $errmsg, $referrals, $controls);
if ($errcode === LDAP_SUCCESS) {
echo 'Eintrag erfolgreich umbenannt.';
} else {
echo 'LDAP-Fehler ' . $errcode . ': ' . $errmsg;
}
}
ldap_unbind($ldap);Eintrag umbenennen und in anderen OU verschieben
<?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');
// Eintrag von ou=Users nach ou=Alumni verschieben und RDN beibehalten
$dn = 'cn=Erika Muster,ou=Users,dc=example,dc=com';
$newRdn = 'cn=Erika Muster'; // gleicher RDN
$newParent = 'ou=Alumni,dc=example,dc=com'; // neuer übergeordneter DN
$result = ldap_rename_ext($ldap, $dn, $newRdn, $newParent, true);
if ($result === false) {
echo 'Fehler: ' . ldap_error($ldap);
} else {
ldap_parse_result($ldap, $result, $errcode);
echo ($errcode === LDAP_SUCCESS)
? 'Eintrag erfolgreich verschoben.'
: 'Fehlercode: ' . $errcode;
}
ldap_unbind($ldap);// Wichtig · Fallstricke
Berechtigungen: Für das Umbenennen von LDAP-Einträgen sind in der Regel Schreibrechte auf dem Verzeichnisserver erforderlich. Das Bind-Konto muss über ausreichende Zugriffsrechte verfügen.
Unterschied zu ldap_rename: Während ldap_rename ein einfaches true oder false zurückgibt, ermöglicht ldap_rename_ext die Auswertung von Server-Controls und detaillierten Fehlerinformationen über ldap_parse_result.
LDAP v3 erforderlich: Das Umbenennen in einen anderen Zweig des Verzeichnisbaums (andere übergeordnete OU) ist nur mit LDAPv3 möglich. Stellen Sie sicher, dass ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3) gesetzt ist.
Sicherheitshinweis: DN-Werte, die aus Benutzereingaben stammen, müssen vor der Verwendung mit ldap_escape und dem Flag LDAP_ESCAPE_DN escaped werden, um LDAP-Injection zu verhindern.