# Zend_Ldap

`Zend_Ldap` ist das Basisinterface zum LDAP Server. Es bietet Verbindungs- und Bindungsmethode sowie Methoden um auf dem LDAP Baum zu arbeiten.

## Zend_Ldap API

Methode | Beschreibung
--- | ---
`string filterEscape(string $str)` | Escapt einen Wert damit dieser in einem LDAP Filter entsprechend RFC 2254. Diese Methode ist deprecated, stattdessen sollte `Zend_Ldap_Dn::checkDn()` verwendet werden.
`boolean explodeDn($dn, array &$keys = null, array &$vals = null)` | Prüft ob ein angegebener DN `$dn` fehlerhaft ist. Wenn `$keys` oder `$keys` und `$vals` angegeben werden, werden diese Arrays mit den entsprechenden DN Schlüsseln und Werten gefüllt. Diese Methode ist deprecated, stattdessen sollte `Zend_Ldap_Dn::checkDn()` verwendet werden.
`__construct($options)` | Constructor. Der `$options` Parameter ist Optional und kann ein Array, oder eine Instanz von `Zend_Config` sein. Wenn keine Optionen bei der Instanzierung angegeben werden, müssen die Verbindungsparameter der Instanz übergeben werden indem man `Zend_Ldap::setOptions()` verwendet. Die erlaubten Optionen werden in Zend_Ldap Optionen apezifiziert.
`resource getResource()` | Gibt die rohe Ressource der LDAP Erweiterung (ext/ldap) zurück.
`integer getLastErrorCode()` | Gibt die LDAP Fehlernummer des letzten LDAP Kommandos zurück.
`string getLastError(integer &$errorCode, array &$errorMessages)` | Gibt die LDAP Fehlermeldung des letzten LDAP Kommandos zurück. Der optionale `$errorCode` Parameter ist auf die LDAP Fehlernummer gesetzt wenn er angegeben ist. Die verschiedenen LDAP Funktionen welche Fehler zurückgeben können unterschiedliche Dinge zurückgeben, sodas Sie alle gesammelt werden wenn `$errorMessages` angegeben ist.
`Zend_Ldap setOptions($options)` | Setzt die LDAP Verbindungs- und Bindungsparameter. `$options` kann ein Array oder eine Instanz von `Zend_Config` sein. Die erlauben Optionen werden in Zend_Ldap Optionen definiert.
`array getOptions()` | Gibt die aktuellen Verbindungs- und Bindungsparameter zurück.
`string getBaseDn()` | Gibt den Basis DN zurück auf welche diese LDAP Verbindung gebunden ist.
`string getCanonicalAccountName(string $acctname, integer $form)` | Gibt den kanonischen Account Namen des angegebenen Account Namens `$acctname` zurück. `$form` spezifiziert das Format in das der Account Name kanonisiert wird. Siehe Kanonisierung des Account Namens für weitere Details.
`Zend_Ldap disconnect()` | Trennt die Verbindung der Zend_Ldap Instanz vom LDAP Server.
`Zend_Ldap connect(string $host, integer $port, boolean $useSsl, boolean $useStartTls)` | Verbindet eine Instanz von Zend_Ldap mit dem angegebenen LDAP Server. Alle Parameter sind optional, und werden von den LDAP Verbindungs- und Bindungsparametern genommen welche der Instanz über den Constructor oder über `Zend_Ldap::setOptions()` angegeben wurden, wenn `NULL` angegeben wurde.

`Zend_Ldap bind(string $username, string $password)`

Authentifiziert `$username` mit `$password` beim LDAP Server. Wenn beide Parameter nicht angegeben werden, dann wird die Verbindung mit den Anmeldeinformationen durchgeführt welche in den Verbindungs- und Bindungsparametern angegeben wurden, und ein anonymes Binden wird ausgeführt. Es ist zu beachten dass hierbei anonymes Binden vom LDAP Server erlaubt sein muss. Ein leerer String `''` kann als `$password` zusammen mit einem Benutzernamen übergeben werden wenn, und nur wenn, `allowEmptyPassword` in den Verdinguns- und Bindungsparametern auf `TRUE` gesetzt ist.

`Zend_Ldap_Collection search(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array $attributes, string $sort, string $collectionClass)`

Durchsucht den LDAP Baum mit dem angegebenen `$filter` und den angegebenen Such Parametern.

`string|Zend_Ldap_Filter_Abstract $filter`

  Der Filterstring kann in der Suche verwendet werden, z.B. `(objectClass=posixAccount)`.

`string|Zend_Ldap_Dn $basedn`

  Die Suchbasis für die Suche. Wenn Sie nicht, oder `NULL` angegeben wird, dann wird die `baseDn` der Verbindungs- und Bindungs Parameter verwendet.

`integer $scope`

  Der Suchbereich. `Zend_Ldap::SEARCH_SCOPE_SUB` durchsucht den kompletten Unterbaum inklusive dem `$baseDn` Node. `Zend_Ldap::SEARCH_SCOPE_ONE` schränkt die Suche auf ein Level unter `$baseDn` ein. `Zend_Ldap::SEARCH_SCOPE_BASE` schränkt die Suche auf `$baseDn` selbst ein; das kann verwendet werden um effizient einen einzelnen Eintrag durch deinen DN zu erhalten. Der Standardwert ist `Zend_Ldap::SEARCH_SCOPE_SUB`.

`array $attributes`

  Spezifiziert die Attribute welche in den zurückgegebenen Einträgen enthalten sind. Um alle möglichen Attribute zu inkludieren (ACL Restriktionen können es verhindern das bestimmte Attribute von einem angegebenen Benutzer empfangen werden) kann entweder ein leeres Array `array()` oder `array('*')` an die Methode übergeben werden. Bei einigen LDAP Servern kann man spezielle interne Attribute erhalten wenn man an die Methode `array('*', '+')` übergibt.

`string $sort`

  Ob die Sammlung der Ergebnisse nach dem Attribut `$sort` sortiert werden soll. Ergebnisse können nur nach einem einzelnen Attribut sortiert werden, da dieser Parameter die ext/ldap Funktion `ldap_sort()` verwendet.

`string $collectionClass`

  Ob das Ergebnis in ein Objekt vom Typ `$collectionClass` eingebettet werden soll. Standardmäßig wird ein Objekt vom Typ `Zend_Ldap_Collection` zurückgegeben. Die eigene Klasse muß `Zend_Ldap_Collection` erweitern und wird bei der Instanziierung ein `Zend_Ldap_Collection_Iterator_Default` übergeben.

`integer count(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope)` | Zählt die Elemente welche durch die angegebenen Such Parameter zurückgegeben werden. Siehe `Zend_Ldap::search()` für eine detailierte Beschreibung der Parameter der Methode.
`integer countChildren(string|Zend_Ldap_Dn $dn)` | Zählt die direkten Abhängigkeiten (Kinder) des Eintrags, der durch den angegebenen `$dn` identifiziert wird.
`boolean exists(string|Zend_Ldap_Dn $dn)` | Prüft ob der Eintrag, der durch den angegebenen `$dn` identifiziert wird, existiert.

`array searchEntries(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array $attributes, string $sort)`

Führt eine Such Operation durch und gibt als Ergebnis ein PHP Array zurück. Das ist notwendigerweise die gleiche Methode wie `Zend_Ldap::search()` ausser beim Rückgabe Typ. Siehe `Zend_Ldap::search()` für eine detailierte Beschreibung der Parameter der Methode.

`array getEntry(string|Zend_Ldap_Dn $dn, array $attributes, boolean $throwOnNotFound)`

Gibt den LDAP Eintrag zurück der von `$dn` mit den in `$attributes` angegebenen Attributen identifiziert wird. Wenn `$attributes` unterdrückt wird (`array()`) werden alle Attribute im Ergebnis ausgegeben. `$throwOnNotFound` ist standardmäßig `FALSE`, so dass die Methode `NULL` zurückgibt wemm der spezifizierte Eintrag nicht gefunden wird. Wenn er auf `TRUE` gesetzt ist, wird statt dessen eine `Zend_Ldap_Exception` geworfen.

`void prepareLdapEntryArray(array &$entry)` | Bereitet ein Array für die Verwendung in Modifikations Operationen von LDAP vor. Diese Methode muß nicht von Endbenutzern aufgerufen werden da Sie implizit bei jeder Methode die Daten verändert aufgerufen wird.
`Zend_Ldap add(string|Zend_Ldap_Dn $dn, array $entry)` | Fügt den Eintrag der durch `$dn` mit seinen `$entry` identifiziert wird im LDAP Baum hinzu. Wirft eine `Zend_Ldap_Exception` wenn der Eintrag nicht hinzugefügt werden konnte.
`Zend_Ldap update(string|Zend_Ldap_Dn $dn, array $entry)` | Aktualisiert den Eintrag der durch `$dn` mit seinen `$entry` Attributen identifiziert wird im LDAP Baum. Wirft eine `Zend_Ldap_Exception` wenn der Eintrag nicht geändert werden konnte.
`Zend_Ldap save(string|Zend_Ldap_Dn $dn, array $entry)` | Speichert den Eintrag der durch `$dn` mit seinen `$entry` Attributen identifiziert wird im LDAP Baum. Wirft eine `Zend_Ldap_Exception` wenn der Eintrag nicht gespeichert werden konnte. Diese Methode wählt durch eine Suche im LDAP Baum ob der Eintrag hinzugefügt oder aktualisiert wird.

`Zend_Ldap delete(string|Zend_Ldap_Dn $dn, boolean $recursively)`

Löscht den Eintrag der durch `$dn` identifiziert wird vom LDAP Baum. Wirft eine `Zend_Ldap_Exception` Exception wenn der Eintrag nicht gelöscht werden kann. `$recursively` ist standardmäßig `FALSE`. Auf `TRUE` gesetzt wird das Löschen rekursiv durchgeführt und löscht effektiver Weise den kompletten Unterbaum. Das Löschen wird fehlschlagen wenn `$recursively` `FALSE` ist und der `$dn` Eintrag kein Blatteintrag ist.

`Zend_Ldap moveToSubtree(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively, boolean $alwaysEmulate)`

Verschiebt den Eintrag der von `$from` identifiziert wird auf einen Ort nach `$to` wobei sein RDN unverändert bleibt. `$recursively` spezifiziert ob die Operation rekursiv ausgeführt wird (standardmäßig `FALSE`) so dass der Eintrag `$from` und alle seine Untereinträge verschoben werden. Das Verschieben wird fehlschlagen wenn `$recursively` `FALSE` ist und der Eintrag `$from` kein Blatteintrag ist. `$alwaysEmulate` kontrolliert ob die ext/ldap Funktion `ldap_rename()` verwendet werden soll wenn Sie vorhanden ist. Das kann nur für Blatteinträge funktionieren und für Server und für ext/ldap die diese Funktion unterstützen. Auf `TRUE` gesetzt wird immer eine emulierte Rename Operation verwendet.

Alle Verschiebe-Operationen werden ausgeführt indem die betreffenden Einträge im LDAP Baum kopiert und anschließend gelöscht werden. Diese Operationen sind nicht atomar so dass Fehler wärend der Operation zu einem inkonsistenten Status am LDAP Server führen. Das selbe gilt auch für alle rekursiven Operationen. Auch diese sind in keiner Weise atomar. Man sollte das immer beachten.

`Zend_Ldap move(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively, boolean $alwaysEmulate)` | Das ist ein Alias für `Zend_Ldap::rename()`.

`Zend_Ldap rename(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively, boolean $alwaysEmulate)`

Benennt den Eintrag der von `$from` bis `$to` identifiziert wird um. `$recursively` spezifiziert ob die Operation rekursiv durchgeführt werden soll (standardmäßig `FALSE`) so das der Eintrag `$from` und alle seine Abhängigkeiten verschoben werden. Das Umbenennen wird fehlschlagen wenn `$recursively` `FALSE` ist und der Eintrag `$from` kein Blatteintrag ist. `$alwaysEmulate` kontrolliert ob die ext/ldap Funktion `ldap_rename()` verwendet werden soll wenn Sie vorhanden ist. Das kann nur für Blatteinträge und für Server funktionieren und für ext/ldap welches diese Funktion unterstützt. Wird es auf `TRUE` gesetzt wird immer die emulierte rename Operation verwendet.

`Zend_Ldap copyToSubtree(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively)`

Kopiert den Eintrag der von `$from` bis zu einem Ort unterhalb von `$to` identifiziert wird und lässt dessen RDN unverändert. `$recursively` spezifiziert ob die Operation rekursiv durchgeführt werden soll (standardmäßig `FALSE`) so das der Eintrag `$from` und alle seine Abhängigkeiten kopiert werden. Das Kopieren wird fehlschlagen wenn `$recursively` `FALSE` ist und der Eintrag `$from` kein Blatteintrag ist.

`Zend_Ldap copy(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively)`

Kopiert den Eintrag der von `$from` bis `$to` identifiziert wird. `$recursively` spezifiziert ob die Operation rekursiv durchgeführt werden soll (standardmäßig `FALSE`) so das der Eintrag `$from` und alle seine Abhängigkeiten kopiert werden. Das Kopieren wird fehlschlagen wenn `$recursively` `FALSE` ist und der Eintrag `$from` kein Blatteintrag ist.

`Zend_Ldap_Node getNode(string|Zend_Ldap_Dn $dn)` | Gibt den `$dn` Eintrag zurück der in einem `Zend_Ldap_Node` gewrappt ist.
`Zend_Ldap_Node getBaseNode()` | Gibt den Eintrag für den Basis DN `$baseDn` zurück der in einer `Zend_Ldap_Node` gewrappt ist.
`Zend_Ldap_Node_RootDse getRootDse()` | Gibt den RootDSE für den aktuellen Server zurück.
`Zend_Ldap_Node_Schema getSchema()` | Gibt das LDAP Schema für den aktuellen Server zurück.

## Zend_Ldap_Collection

`Zend_Ldap_Collection` implementiert `Iterator` um das Durchlaufen von Einträgen zu erlauben indem `foreach()` und `Countable` verwendet werden welche in der Lage sind auf `count()` zu Antworten. Mit seiner geschützten `_createEntry()` Methode bietet es einen einfachen Punkt der Erweiterung für Entwickler welche die Notwendigkeit für eigene Ergebnisobjekte haben.

### API für Zend_Ldap_Collection

Methode | Beschreibung
--- | ---
`__construct(Zend_Ldap_Collection_Iterator_Interface $iterator)` | Constructor. Der Constructor muß von einem `Zend_Ldap_Collection_Iterator_Interface` angeboten werden welches die echte Iteration der Resultate durchführt. `Zend_Ldap_Collection_Iterator_Default` ist die standardmäßige Implementation für die Interation durch ext/ldap Ergebnisse.
`boolean close()` | Schließt den internen Iterator. Wird auch im Destructor aufgerufen.
`array toArray()` | Gibt alle Einträge als Array zurück.
`array getFirst()` | Gibt den ersten Eintrag der Collection zurück, oder `NULL` wenn die Collection leer ist.