ldap_rename — Funktion · PHP-Referenz

Signatur

ldap_rename(LDAP\Connection $ldap, string $dn, string $new_rdn, string $new_parent, bool $delete_old_rdn, ?array $controls = null): bool

Beschreibung

ldap_rename() ändert den Namen eines bestehenden LDAP-Eintrags. Dabei kann sowohl der RDN (Relative Distinguished Name, also der letzte Teil des DN) als auch der übergeordnete Eintrag (Parent-DN) geändert werden. Dies entspricht der LDAP-Operation ModifyDN (auch Move oder Rename genannt).

Typische Anwendungsfälle sind das Umbenennen von Benutzern, Gruppen oder Organisationseinheiten in einem Verzeichnisdienst (z. B. Active Directory oder OpenLDAP), ohne den gesamten Eintrag löschen und neu anlegen zu müssen. Durch den Parameter delete_old_rdn kann gesteuert werden, ob der alte RDN-Wert als Attributwert im Eintrag erhalten bleibt oder entfernt wird.

Um einen Eintrag in einen anderen Teil des Verzeichnisbaums zu verschieben, wird new_parent mit dem gewünschten Ziel-DN angegeben. Soll der Eintrag lediglich im selben Container umbenannt werden, übergibt man für new_parent einen leeren String oder null.

Ab PHP 8.1.0 wurde der erste Parameter von einer Ressource auf das Objekt LDAP\Connection umgestellt. Der optionale Parameter controls erlaubt es, LDAP-Server-Controls mitzuschicken, z. B. für Proxied Authorization.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine gültige LDAP-Verbindung, die zuvor mit `ldap_connect()` und `ldap_bind()` aufgebaut wurde.
$dn Pflicht	string		Der vollständige 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=Maximilian Mustermann`.
$new_parent Pflicht	string		Der DN des neuen übergeordneten Eintrags. Wenn der Eintrag nur umbenannt (nicht verschoben) werden soll, wird ein leerer String übergeben.
$delete_old_rdn Pflicht	bool		Wenn `true`, wird der alte RDN-Attributwert aus dem Eintrag entfernt. Bei `false` bleibt der alte Wert als zusätzliches Attribut erhalten.
$controls	array\|null	null	Ein optionales Array mit LDAP-Server-Controls, die mit der Anfrage gesendet werden sollen. Verfügbar ab PHP 7.3.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler. Im Fehlerfall kann ldap_error() zur Fehlerdiagnose verwendet werden.

Beispiele

Einfaches Umbenennen eines LDAP-Benutzers

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

if (!ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort')) {
    die('Bind fehlgeschlagen: ' . ldap_error($ldap));
}

$oldDn    = 'cn=Max Mustermann,ou=users,dc=example,dc=com';
$newRdn   = 'cn=Maximilian Mustermann';
$newParent = ''; // Kein Verschieben, nur umbenennen

$result = ldap_rename($ldap, $oldDn, $newRdn, $newParent, true);

if ($result) {
    echo "Eintrag erfolgreich umbenannt.";
} else {
    echo "Fehler: " . ldap_error($ldap);
}

ldap_unbind($ldap);

Eintrag erfolgreich umbenannt.

Benutzer in eine andere Organisationseinheit verschieben

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

if (!ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort')) {
    die('Bind fehlgeschlagen: ' . ldap_error($ldap));
}

// Benutzer von ou=users nach ou=archiv verschieben und dabei umbenennen
$oldDn     = 'cn=Max Mustermann,ou=users,dc=example,dc=com';
$newRdn    = 'cn=Max Mustermann'; // RDN bleibt gleich
$newParent = 'ou=archiv,dc=example,dc=com'; // Neues Eltern-Element

$result = ldap_rename($ldap, $oldDn, $newRdn, $newParent, true);

if ($result) {
    echo "Eintrag erfolgreich verschoben nach ou=archiv.";
} else {
    echo "Fehler beim Verschieben: " . ldap_error($ldap);
}

ldap_unbind($ldap);

Eintrag erfolgreich verschoben nach ou=archiv.

// Wichtig · Fallstricke

Berechtigungen: Der gebundene Benutzer benötigt ausreichende Schreibrechte (write/modify) auf den betreffenden Eintrag sowie das Ziel-Elternobjekt. Ohne entsprechende ACLs schlägt die Operation mit einem Berechtigungsfehler fehl.

LDAP v3 erforderlich: Die ModifyDN-Operation (Verschieben in einen anderen Container) ist erst ab LDAP-Protokollversion 3 möglich. Stelle sicher, dass ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3) vor dem Bind aufgerufen wird.

Active Directory: Beim Einsatz mit Microsoft Active Directory muss der LDAP-Server über eine gesicherte Verbindung (LDAPS oder StartTLS) gebunden sein, um Einträge zu verschieben oder umzubenennen. Andernfalls verweigert AD die Operation.

Änderung in PHP 8.1: Der Parameter ldap erwartet ab PHP 8.1.0 ein Objekt vom Typ LDAP\Connection statt einer Ressource. Bei Verwendung älterer Versionen ist der Typ resource.

Siehe auch

ldap_connect ldap_bind ldap_add ldap_delete ldap_modify ldap_error