Signatur
Beschreibung
ldap_add_ext ist die erweiterte Variante von ldap_add. Sie fügt einen neuen Eintrag mit dem angegebenen Distinguished Name (DN) und den zugehörigen Attributen in ein LDAP-Verzeichnis ein. Im Gegensatz zur einfachen Variante gibt diese Funktion ein LDAP\Result-Objekt zurück, über das das Ergebnis der Operation – inklusive etwaiger Server-Controls – gezielt analysiert werden kann.
Der Parameter $entry ist ein assoziatives Array, dessen Schlüssel LDAP-Attributnamen sind. Jeder Wert kann entweder ein einzelner String oder ein Array von Strings sein, wenn ein Attribut mehrere Werte besitzt (z. B. objectClass). Das Pflichtattribut objectClass muss immer angegeben werden.
Über den Parameter $controls können LDAP-Server-Controls (z. B. zum Auslösen von Pre-/Post-Read oder Password-Policy-Controls) als Array übergeben werden. Dies ermöglicht feinkörnigere Steuerung des Serververhaltens, die mit ldap_add nicht möglich ist.
Die Funktion eignet sich besonders in modernem PHP-Code (ab 8.0), wo die objektorientierte LDAP-API (LDAP\Connection, LDAP\Result) gegenüber den älteren Ressource-basierten Typen bevorzugt wird.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ldap Pflicht | LDAP\Connection | Eine gültige LDAP-Verbindungsinstanz, wie sie von ldap_connect zurückgegeben wird. |
|
| $dn Pflicht | string | Der Distinguished Name (DN) des neu hinzuzufügenden Eintrags, z. B. cn=Max Mustermann,ou=users,dc=example,dc=com. |
|
| $entry Pflicht | array | Assoziatives Array mit den Attributen des neuen Eintrags. Schlüssel sind Attributnamen, Werte entweder Strings oder Arrays von Strings bei mehrwertigen Attributen. | |
| $controls | array|null | null | Optionales Array von LDAP-Server-Controls, die mit der Anfrage gesendet werden sollen. Jedes Control ist ein assoziatives Array mit den Schlüsseln oid, iscritical und optional value. |
Rückgabewert
LDAP\Result-Objekt zurück, das mit Funktionen wie ldap_parse_result ausgewertet werden kann. Gibt false zurück, wenn ein Fehler aufgetreten ist (z. B. unzureichende Berechtigungen, ungültiger DN oder Verbindungsfehler).Beispiele
Neuen Benutzer im LDAP-Verzeichnis anlegen
<?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';
$entry = [
'objectClass' => ['top', 'person', 'organizationalPerson', 'inetOrgPerson'],
'cn' => 'Max Mustermann',
'sn' => 'Mustermann',
'givenName' => 'Max',
'mail' => 'max.mustermann@example.com',
'userPassword'=> '{SHA}' . base64_encode(sha1('passwort123', true)),
];
$result = ldap_add_ext($ldap, $dn, $entry);
if ($result === false) {
echo 'Fehler beim Hinzufügen: ' . ldap_error($ldap);
} else {
ldap_parse_result($ldap, $result, $errCode, $matchedDn, $errMsg);
if ($errCode === LDAP_SUCCESS) {
echo 'Eintrag erfolgreich hinzugefügt.';
} else {
echo "LDAP-Fehler {$errCode}: {$errMsg}";
}
}
ldap_unbind($ldap);Eintrag mit Server-Control (Pre-Read) hinzufügen
<?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=Erika Musterfrau,ou=users,dc=example,dc=com';
$entry = [
'objectClass' => ['top', 'person', 'inetOrgPerson'],
'cn' => 'Erika Musterfrau',
'sn' => 'Musterfrau',
'mail' => 'erika@example.com',
];
// Pre-Read Control: Server soll den Eintrag vor dem Schreiben zurückliefern
$controls = [
[
'oid' => LDAP_CONTROL_PRE_READ,
'iscritical' => false,
'value' => ['attrs' => ['cn', 'mail']],
]
];
$result = ldap_add_ext($ldap, $dn, $entry, $controls);
if ($result !== false) {
ldap_parse_result($ldap, $result, $errCode, $matchedDn, $errMsg, $referrals, $returnedControls);
echo 'Eintrag hinzugefügt, LDAP-Code: ' . $errCode . PHP_EOL;
// $returnedControls enthält ggf. Pre-Read-Daten
var_dump($returnedControls);
} else {
echo 'Fehler: ' . ldap_error($ldap);
}
ldap_unbind($ldap);// Wichtig · Fallstricke
Sicherheit: Stellen Sie sicher, dass alle Attributwerte, die aus Benutzereingaben stammen, validiert und korrekt escaped werden, bevor sie als $entry oder $dn übergeben werden. Unsanitierte Eingaben können zu LDAP-Injection führen. Nutzen Sie ldap_escape mit dem Flag LDAP_ESCAPE_DN für DN-Komponenten und LDAP_ESCAPE_FILTER für Filterwerte.
Unterschied zu ldap_add: ldap_add gibt lediglich true oder false zurück. ldap_add_ext liefert hingegen ein auswertbares LDAP\Result-Objekt, was die Auswertung von Server-Controls und detaillierten Fehlercodes ermöglicht.
Berechtigungen: Der gebundene LDAP-Benutzer benötigt das Schreibrecht auf die übergeordnete Organisationseinheit. Andernfalls schlägt die Operation mit einem LDAP-Fehlercode (z. B. LDAP_INSUFFICIENT_ACCESS) fehl.
Hinweis zu objectClass: Das Attribut objectClass ist Pflicht und muss alle notwendigen strukturellen und auxilären Klassen des Eintrags enthalten. Fehlt es oder ist es unvollständig, wird der Server die Anfrage mit einem Schema-Verletzungsfehler ablehnen.