ldap_mod_add_ext — Funktion · PHP-Referenz

Signatur

ldap_mod_add_ext(LDAP\Connection $ldap, string $dn, array $entry, ?array $controls = null): LDAP\Result|false

Beschreibung

ldap_mod_add_ext ergänzt einem bestehenden LDAP-Eintrag (identifiziert durch seinen Distinguished Name $dn) neue Attributwerte, ohne vorhandene Werte zu überschreiben. Die Funktion ist die erweiterte Variante von ldap_mod_add: Statt eines booleschen Ergebnisses gibt sie ein LDAP\Result-Objekt zurück, das anschließend mit ldap_parse_result oder ldap_get_entries weiterverarbeitet werden kann.

Dies erlaubt asynchrones bzw. detaillierteres Arbeiten mit dem LDAP-Ergebnis, z. B. das Auslesen von Server-Controls aus der Antwort. Besonders nützlich ist die Funktion, wenn LDAP-Controls (Server-seitige Steuerbefehle) mitgesendet werden sollen, etwa für Paging, Sortierung oder Zugriffskontrolle.

Typische Anwendungsfälle sind das Hinzufügen weiterer E-Mail-Adressen zu einem bestehenden mail-Attribut, das Eintragen eines Benutzers in eine zusätzliche Gruppe über das member-Attribut oder das Erweitern von objectClass-Einträgen.

Die Funktion erfordert eine aktive, authentifizierte LDAP-Verbindung. Das Array $entry muss die Attributnamen als Schlüssel und die hinzuzufügenden Werte (als Array oder Zeichenkette) als Werte enthalten.

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. `uid=jdoe,ou=users,dc=example,dc=com`.
$entry Pflicht	array		Assoziatives Array, dessen Schlüssel Attributnamen sind und dessen Werte die hinzuzufügenden Werte (Zeichenkette oder Array von Zeichenketten) darstellen.
$controls	array\|null	null	Ein optionales Array von LDAP-Controls, die mit der Anfrage gesendet werden. Jeder Eintrag ist ein assoziatives Array mit den Schlüsseln `oid`, `iscritical` und `value`.

Rückgabewert

Typ

LDAP\Result|false

Beschreibung

Gibt bei Erfolg ein LDAP\Result-Objekt zurück, das mit Funktionen wie ldap_parse_result ausgewertet werden kann. Bei einem Fehler wird false zurückgegeben; mit ldap_error oder ldap_errno lässt sich der genaue Fehler ermitteln.

Beispiele

E-Mail-Adresse zu einem bestehenden LDAP-Benutzer 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 = 'uid=jdoe,ou=users,dc=example,dc=com';

// Neue E-Mail-Adresse zum Attribut 'mail' hinzufügen
$entry = [
    'mail' => 'john.doe.alias@example.com',
];

$result = ldap_mod_add_ext($ldap, $dn, $entry);

if ($result === false) {
    echo 'Fehler: ' . ldap_error($ldap);
} else {
    ldap_parse_result($ldap, $result, $errcode, $matcheddn, $errmsg);
    if ($errcode === LDAP_SUCCESS) {
        echo 'E-Mail-Adresse erfolgreich hinzugefügt.';
    } else {
        echo 'LDAP-Fehler ' . $errcode . ': ' . $errmsg;
    }
}

ldap_unbind($ldap);

E-Mail-Adresse erfolgreich hinzugefügt.

Benutzer einer LDAP-Gruppe hinzufügen (mit Server-Control)

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

$groupDn = 'cn=developers,ou=groups,dc=example,dc=com';

// Benutzer-DN als neues member-Attribut zur Gruppe hinzufügen
$entry = [
    'member' => 'uid=jdoe,ou=users,dc=example,dc=com',
];

// Optional: Proxy-Authorization-Control mitsenden
$controls = [
    [
        'oid'        => LDAP_CONTROL_PROXY_AUTHZ,
        'iscritical' => true,
        'value'      => 'dn:cn=admin,dc=example,dc=com',
    ],
];

$result = ldap_mod_add_ext($ldap, $groupDn, $entry, $controls);

if ($result === false) {
    echo 'Fehler beim Hinzufügen: ' . ldap_error($ldap);
} else {
    ldap_parse_result($ldap, $result, $errcode);
    echo $errcode === LDAP_SUCCESS
        ? 'Benutzer erfolgreich der Gruppe hinzugefügt.'
        : 'Fehlercode: ' . $errcode;
}

ldap_unbind($ldap);

Benutzer erfolgreich der Gruppe hinzugefügt.

// Wichtig · Fallstricke

Berechtigungen: Der bindende Benutzer muss ausreichende Schreibrechte auf den Ziel-DN besitzen. Andernfalls schlägt die Operation mit einem LDAP_INSUFFICIENT_ACCESS-Fehler fehl.

Duplikatprüfung: Viele LDAP-Server (z. B. OpenLDAP) verhindern das doppelte Hinzufügen eines bereits vorhandenen Attributwerts und liefern einen Fehler (LDAP_TYPE_OR_VALUE_EXISTS). Vor dem Aufruf sollte geprüft werden, ob der Wert bereits existiert.

Unterschied zu ldap_mod_add: ldap_mod_add gibt nur true oder false zurück. ldap_mod_add_ext ermöglicht zusätzlich das Auslesen von Server-Controls aus der Antwort und ist daher die bevorzugte Wahl, wenn Controls verwendet werden oder detaillierte Fehlerinformationen benötigt werden.

PHP-Version: Diese Funktion ist erst ab PHP 8.0.0 verfügbar, da LDAP\Connection und LDAP\Result als echte Objekte erst mit PHP 8.1 vollständig eingeführt wurden; für ältere PHP-Versionen steht nur ldap_mod_add zur Verfügung.

Siehe auch

ldap_mod_add ldap_mod_del_ext ldap_mod_replace_ext ldap_modify_batch ldap_parse_result ldap_error ldap_bind