ldap_mod_replace — Funktion · PHP-Referenz

Signatur

ldap_mod_replace(LDAP\Connection $ldap, string $dn, array $entry, array $controls = []): bool

Beschreibung

ldap_mod_replace ersetzt alle vorhandenen Werte eines oder mehrerer Attribute eines LDAP-Eintrags durch die angegebenen neuen Werte. Im Gegensatz zu ldap_mod_add (das Werte hinzufügt) oder ldap_mod_del (das Werte löscht) überschreibt diese Funktion die Attributwerte vollständig. Wenn ein Attribut bisher nicht existierte, wird es neu angelegt.

Die Funktion wird typischerweise verwendet, wenn ein Attribut (z. B. ein Passwort, eine E-Mail-Adresse oder ein Telefonnummernfeld) auf einen neuen, bekannten Wert gesetzt werden soll, ohne den bisherigen Inhalt zu berücksichtigen. Es muss zuvor eine gültige LDAP-Verbindung über ldap_connect und ein erfolgreicher Bind über ldap_bind mit ausreichenden Rechten hergestellt worden sein.

Das Array $entry ordnet Attributnamen (als Schlüssel) ihren neuen Werten (als einfache Strings oder als Array von Strings bei mehrwertigen Attributen) zu. Wird ein leeres Array als Wert übergeben, werden alle bestehenden Werte des Attributs gelöscht.

Ab PHP 8.1.0 ist der erste Parameter ein LDAP\Connection-Objekt; in früheren Versionen war es eine PHP-Ressource. Außerdem wurde der Parameter $controls ab PHP 7.3.0 eingeführt, um LDAP-Server-Controls mitzusenden.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine gültige LDAP-Verbindungsinstanz, die mit `ldap_connect` erzeugt und mit `ldap_bind` authentifiziert wurde.
$dn Pflicht	string		Der Distinguished Name (DN) des LDAP-Eintrags, dessen Attribute ersetzt werden sollen, z. B. `uid=jdoe,ou=users,dc=example,dc=com`.
$entry Pflicht	array		Assoziatives Array mit Attributnamen als Schlüssel und den neuen Werten als Strings oder Arrays. Beispiel: `['mail' => 'neu@example.com', 'telephoneNumber' => ['0301234', '0309876']]`. Ein leeres Array als Wert löscht das Attribut.
$controls	array	[]	Array mit LDAP-Server-Controls, die mit der Anfrage gesendet werden sollen. Seit PHP 7.3.0 verfügbar.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Operation erfolgreich war, andernfalls false. Im Fehlerfall können mit ldap_error und ldap_errno weitere Informationen abgerufen werden.

Beispiele

E-Mail-Adresse eines Benutzers ersetzen

<?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));
}

$dn = 'uid=jdoe,ou=users,dc=example,dc=com';
$entry = [
    'mail' => 'jdoe_neu@example.com',
];

if (ldap_mod_replace($ldap, $dn, $entry)) {
    echo 'E-Mail-Adresse erfolgreich ersetzt.';
} else {
    echo 'Fehler: ' . ldap_error($ldap);
}

ldap_unbind($ldap);

E-Mail-Adresse erfolgreich ersetzt.

Mehrere Attribute gleichzeitig ersetzen und ein Attribut löschen

<?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 = 'uid=jdoe,ou=users,dc=example,dc=com';
$entry = [
    'sn'              => 'Doe-Mustermann',
    'telephoneNumber' => ['0301234567', '0309876543'],
    'description'     => [], // Attribut komplett löschen
];

if (ldap_mod_replace($ldap, $dn, $entry)) {
    echo 'Attribute wurden erfolgreich aktualisiert.';
} else {
    echo 'Fehler beim Ersetzen: ' . ldap_error($ldap);
}

ldap_unbind($ldap);

Attribute wurden erfolgreich aktualisiert.

// Wichtig · Fallstricke

Berechtigungen: Der gebundene LDAP-Benutzer muss ausreichende Schreibrechte auf den Ziel-DN besitzen, sonst schlägt die Operation mit einem Fehler fehl (z. B. LDAP-Fehlercode 50: Insufficient Access Rights).

Passwörter in Active Directory: Beim Ersetzen des unicodePwd-Attributs in Active Directory muss das Passwort UTF-16LE-kodiert und in Anführungszeichen eingeschlossen sein. Außerdem ist zwingend eine verschlüsselte Verbindung (LDAPS oder StartTLS) erforderlich.

Ressource vs. Objekt: Ab PHP 8.1.0 ist der Verbindungsparameter ein LDAP\Connection-Objekt. Code, der noch mit Ressourcen arbeitet, muss entsprechend angepasst werden.

Atomarität: Sollen mehrere Änderungen atomar durchgeführt werden, sollte stattdessen ldap_modify_batch verwendet werden, das eine Transaktion über mehrere Attributoperationen ermöglicht.

Siehe auch

ldap_mod_add ldap_mod_del ldap_modify ldap_modify_batch ldap_connect ldap_bind ldap_error