ldap_add — Funktion · PHP-Referenz

Signatur

ldap_add(LDAP\Connection $ldap, string $dn, array $entry, ?array $controls = null): bool

Beschreibung

ldap_add() erstellt einen neuen Eintrag in einem LDAP-Verzeichnis. Der Eintrag wird über seinen Distinguished Name (DN) eindeutig identifiziert. Die Attribute des Eintrags werden als assoziatives Array übergeben, wobei jeder Schlüssel den Attributnamen und der zugehörige Wert entweder einen einzelnen Wert (String) oder mehrere Werte (Array von Strings) enthält.

Voraussetzung für den erfolgreichen Aufruf ist eine zuvor hergestellte und authentifizierte LDAP-Verbindung via ldap_connect() und ldap_bind(). Der bindende Benutzer muss im Verzeichnis über ausreichende Schreibrechte verfügen, um Einträge unterhalb des Ziel-DNs anzulegen.

Der Parameter $controls (ab PHP 7.3 verfügbar) erlaubt es, LDAP-Server-Controls mitzuschicken, beispielsweise für Transaktionssteuerung oder besondere Verarbeitungsoptionen. Wird null übergeben, werden keine zusätzlichen Controls verwendet.

Typische Anwendungsfälle sind das Anlegen von Benutzerkonten, Gruppen oder Organisationseinheiten in Verzeichnisdiensten wie OpenLDAP oder Active Directory.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine gültige LDAP-Verbindungsressource, die mit `ldap_connect()` erzeugt und mit `ldap_bind()` authentifiziert wurde.
$dn Pflicht	string		Der vollständige Distinguished Name (DN) des neu anzulegenden Eintrags, z. B. `cn=Max Mustermann,ou=users,dc=example,dc=com`.
$entry Pflicht	array		Assoziatives Array mit den Attributen des Eintrags. Schlüssel sind Attributnamen (Strings), Werte sind entweder ein einzelner String oder ein Array aus Strings bei mehrwertigen Attributen. Pflichtattribute (z. B. `objectClass`) müssen entsprechend dem LDAP-Schema gesetzt werden.
$controls	array\|null	null	Optionales Array von LDAP-Server-Controls, die mit der Anfrage gesendet werden sollen. Ab PHP 7.3 verfügbar. Bei `null` werden keine zusätzlichen Controls verwendet.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Eintrag erfolgreich hinzugefügt wurde. Bei einem Fehler (z. B. unzureichende Rechte, bereits existierender DN oder Schemaverstoß) wird false zurückgegeben. Detailliertere Fehlerinformationen liefern ldap_error() und ldap_errno().

Beispiele

Neuen Benutzer im LDAP-Verzeichnis anlegen

<?php
$ldap = ldap_connect('ldap://ldap.example.com');
if (!$ldap) {
    die('Verbindung fehlgeschlagen');
}

ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);

$bound = ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesPasswort');
if (!$bound) {
    die('Authentifizierung fehlgeschlagen: ' . ldap_error($ldap));
}

$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',
    'uid'         => 'mmustermann',
    'userPassword' => '{SHA}' . base64_encode(sha1('sicheresPasswort', true)),
];

if (ldap_add($ldap, $dn, $entry)) {
    echo 'Benutzer erfolgreich angelegt.';
} else {
    echo 'Fehler beim Anlegen: ' . ldap_error($ldap);
}

ldap_unbind($ldap);
?>

Benutzer erfolgreich angelegt.

Organisationseinheit (OU) 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 = 'ou=Abteilung IT,dc=example,dc=com';

$entry = [
    'objectClass' => ['top', 'organizationalUnit'],
    'ou'          => 'Abteilung IT',
    'description' => 'IT-Abteilung des Unternehmens',
];

if (ldap_add($ldap, $dn, $entry)) {
    echo 'Organisationseinheit erfolgreich angelegt.';
} else {
    echo 'Fehler: ' . ldap_error($ldap);
}

ldap_unbind($ldap);
?>

Organisationseinheit erfolgreich angelegt.

// Wichtig · Fallstricke

Sicherheit: Benutzereingaben, die in den DN oder Attributwerte einfließen, müssen mit ldap_escape() bereinigt werden, um LDAP-Injection-Angriffe zu verhindern. Verwende LDAP_ESCAPE_DN für DN-Komponenten und LDAP_ESCAPE_FILTER für Filterwerte.

Schemakonformität: Der Eintrag muss alle Pflichtattribute des angegebenen objectClass enthalten, andernfalls schlägt der Aufruf mit einem Schemafehler fehl. Welche Attribute erforderlich sind, hängt von der LDAP-Serverkonfiguration ab.

Rückgabewert bei Fehlern: ldap_add() gibt bei Misserfolg false zurück, ohne eine PHP-Exception zu werfen. Nutze immer ldap_error($ldap) oder ldap_errno($ldap) zur Fehlerdiagnose.

Ab PHP 8.1: Der Typ des $ldap-Parameters wurde von der veralteten Ressource (resource) auf das Objekt LDAP\Connection umgestellt.

Siehe auch

ldap_connect ldap_bind ldap_delete ldap_modify ldap_escape ldap_error ldap_errno ldap_unbind