ldap_mod_replace_ext — Funktion · PHP-Referenz

Signatur

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

Beschreibung

ldap_mod_replace_ext führt eine LDAP-Modify-Operation durch, bei der bestehende Attributwerte eines Verzeichniseintrags vollständig durch die angegebenen neuen Werte ersetzt werden. Im Unterschied zu ldap_mod_replace gibt diese Funktion ein LDAP\Result-Objekt zurück, das eine asynchrone Auswertung ermöglicht – etwa mit ldap_parse_result.

Die Funktion eignet sich besonders dann, wenn LDAP-Server-Controls (z. B. ein Pre-Read- oder Post-Read-Control) benötigt werden oder wenn mehrere LDAP-Operationen in einer Pipeline verarbeitet werden sollen, ohne auf das sofortige Ergebnis warten zu müssen.

Der Parameter entry ist ein assoziatives Array, dessen Schlüssel die Attributnamen und dessen Werte Arrays mit den neuen Attributwerten sind. Alle bisherigen Werte des jeweiligen Attributs werden vollständig überschrieben. Um ein Attribut vollständig zu löschen, kann ein leeres Array als Wert übergeben werden.

Voraussetzung ist eine aktive LDAP-Verbindung mit ausreichenden Schreibrechten für den betreffenden Distinguished Name (DN). Das zurückgegebene LDAP\Result-Objekt muss anschließend mit ldap_parse_result ausgewertet werden, um den tatsächlichen Erfolg der Operation zu prüfen.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine aktive LDAP-Verbindungsressource, die zuvor mit `ldap_connect` und `ldap_bind` erstellt 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 den zu ersetzenden Attributen. Schlüssel sind die Attributnamen, Werte sind Arrays mit den neuen Attributwerten. Ein leeres Array als Wert löscht das Attribut vollständig.
$controls	array\|null	null	Optionales Array mit 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

Typ

LDAP\Result|false

Beschreibung

Gibt bei Erfolg ein LDAP\Result-Objekt zurück, das mit ldap_parse_result ausgewertet werden kann. Im Fehlerfall (z. B. ungültige Verbindung, fehlende Rechte) wird false zurückgegeben.

Beispiele

Telefonnummer eines Benutzers ersetzen

<?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 = [
    'telephoneNumber' => ['+49 30 12345678', '+49 171 9876543'],
];

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

if ($result === false) {
    echo 'Fehler beim Senden der Modify-Anfrage: ' . ldap_error($ldap);
} else {
    $errcode  = 0;
    $matcheddn = '';
    $errmsg   = '';
    $referrals = [];
    ldap_parse_result($ldap, $result, $errcode, $matcheddn, $errmsg, $referrals);
    if ($errcode === LDAP_SUCCESS) {
        echo 'Telefonnummer erfolgreich ersetzt.';
    } else {
        echo 'LDAP-Fehler ' . $errcode . ': ' . $errmsg;
    }
}

ldap_unbind($ldap);

Telefonnummer erfolgreich ersetzt.

Attribut mit Post-Read-Control ersetzen

<?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 = [
    'mail' => ['jdoe@neu.example.com'],
];

// Post-Read-Control: OID 1.3.6.1.1.13.2
$controls = [
    [
        'oid'        => '1.3.6.1.1.13.2',
        'iscritical' => false,
        'value'      => 'mail',
    ],
];

$result = ldap_mod_replace_ext($ldap, $dn, $entry, $controls);

if ($result === false) {
    echo 'Fehler: ' . ldap_error($ldap);
} else {
    $errcode = 0;
    ldap_parse_result($ldap, $result, $errcode);
    echo 'Ergebniscode: ' . $errcode;
}

ldap_unbind($ldap);

Ergebniscode: 0

// Wichtig · Fallstricke

Sicherheitshinweis: Übergeben Sie niemals vom Benutzer kontrollierte Werte ungefiltert als DN oder Attributwert. Verwenden Sie ldap_escape, um DN-Komponenten und Filterwerte korrekt zu escapen und LDAP-Injection zu verhindern.

Asynchronität: Im Gegensatz zu ldap_mod_replace blockiert diese Funktion nicht bis zum Eingang der Server-Antwort. Das zurückgegebene LDAP\Result-Objekt muss zwingend mit ldap_parse_result ausgewertet werden – andernfalls bleibt unklar, ob die Operation tatsächlich erfolgreich war.

Berechtigungen: Der gebundene Benutzer benötigt Schreibrechte (write access) auf die Attribute des betreffenden Eintrags im LDAP-Verzeichnis. Fehlen diese, schlägt die Operation mit einem LDAP_INSUFFICIENT_ACCESS-Fehler fehl.

Siehe auch

ldap_mod_replace ldap_mod_add_ext ldap_mod_del_ext ldap_modify_batch ldap_parse_result ldap_escape