Signatur
Beschreibung
ldap_modify_batch ermöglicht es, mehrere Attributänderungen an einem LDAP-Eintrag atomisch in einem einzigen LDAP-Modify-Request durchzuführen. Jede Änderung wird als assoziatives Array mit den Schlüsseln attrib (Attributname), modtype (Änderungstyp) und optional values (ein Array von Werten) beschrieben.
Als Änderungstypen stehen die Konstanten LDAP_MODIFY_BATCH_ADD (Werte hinzufügen), LDAP_MODIFY_BATCH_REMOVE (bestimmte Werte entfernen), LDAP_MODIFY_BATCH_REMOVE_ALL (alle Werte eines Attributs entfernen) und LDAP_MODIFY_BATCH_REPLACE (Werte vollständig ersetzen) zur Verfügung.
Im Vergleich zu mehreren einzelnen Aufrufen von ldap_mod_add, ldap_mod_del oder ldap_mod_replace ist ldap_modify_batch effizienter und sorgt dafür, dass alle Änderungen zusammen angewendet oder im Fehlerfall gemeinsam abgelehnt werden — dies ist besonders wichtig bei komplexen Schreiboperationen auf LDAP-Verzeichnissen.
Der optionale Parameter $controls erlaubt die Übergabe von LDAP-Steuererweiterungen (Server Controls), zum Beispiel für Passwort-Policy- oder Pre-/Post-Read-Erweiterungen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection | Eine gültige LDAP-Verbindungsressource, wie sie von ldap_connect zurückgegeben wird. |
|
| $dn Pflicht | string | Der Distinguished Name (DN) des LDAP-Eintrags, der geändert werden soll, z. B. cn=Max Mustermann,ou=users,dc=example,dc=com. |
|
| $modifications_info Pflicht | array | Ein numerisch indiziertes Array von Änderungs-Arrays. Jedes Änderungs-Array muss die Schlüssel attrib (string, Attributname), modtype (int, eine der LDAP_MODIFY_BATCH_*-Konstanten) und values (array, bei LDAP_MODIFY_BATCH_REMOVE_ALL nicht erforderlich) enthalten. |
|
| $controls | array|null | null | Ein optionales Array von LDAP-Server-Controls, das an den Server gesendet wird. Wird nur von Servern unterstützt, die entsprechende Erweiterungen implementieren. |
Rückgabewert
true bei Erfolg zurück. Im Fehlerfall (z. B. unzureichende Rechte, ungültiger DN, Schemaverstoß) wird false zurückgegeben und ein LDAP-Fehler gesetzt, der mit ldap_error ausgelesen werden kann.Beispiele
E-Mail ersetzen, Telefonnummer hinzufügen und ein Attribut entfernen
<?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';
$modifications = [
[
'attrib' => 'mail',
'modtype' => LDAP_MODIFY_BATCH_REPLACE,
'values' => ['max.mustermann@example.com'],
],
[
'attrib' => 'telephoneNumber',
'modtype' => LDAP_MODIFY_BATCH_ADD,
'values' => ['+49 30 1234567'],
],
[
'attrib' => 'description',
'modtype' => LDAP_MODIFY_BATCH_REMOVE_ALL,
],
];
$result = ldap_modify_batch($ldap, $dn, $modifications);
if ($result) {
echo 'Änderungen erfolgreich angewendet.';
} else {
echo 'Fehler: ' . ldap_error($ldap);
}
ldap_unbind($ldap);
?>Gezieltes Entfernen eines einzelnen Wertes aus einem Mehrwert-Attribut
<?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';
// Nur den alten Wert aus dem Mehrwert-Attribut entfernen
$modifications = [
[
'attrib' => 'telephoneNumber',
'modtype' => LDAP_MODIFY_BATCH_REMOVE,
'values' => ['+49 30 9999999'],
],
];
if (ldap_modify_batch($ldap, $dn, $modifications)) {
echo 'Telefonnummer erfolgreich entfernt.';
} else {
echo 'Fehler: ' . ldap_error($ldap);
}
ldap_unbind($ldap);
?>// Wichtig · Fallstricke
Berechtigungen: Die gebundene LDAP-Identität muss ausreichende Schreibrechte auf den Ziel-DN besitzen. Bei unzureichenden Rechten schlägt die Operation mit einem Insufficient Access Rights-Fehler fehl.
Atomarität: Zwar werden alle Änderungen in einem einzigen LDAP-Request übertragen, jedoch garantieren nicht alle LDAP-Server echte Transaktionalität. Die meisten gängigen Server (z. B. OpenLDAP, Active Directory) verarbeiten die Operationen innerhalb des Requests als Einheit und wenden entweder alle oder keine an.
Passwörter ändern: Beim Ändern des userPassword-Attributs ist zu beachten, dass viele LDAP-Server eine verschlüsselte Verbindung (LDAPS oder STARTTLS) erfordern. Sensible Attributänderungen sollten stets über eine gesicherte Verbindung übertragen werden.
Parameterformat: Das Fehlen des Schlüssels values ist nur bei LDAP_MODIFY_BATCH_REMOVE_ALL zulässig. Bei allen anderen Typen führt ein fehlendes oder leeres values-Array zu einem Fehler.