repo_zf1/documentation/manual/de/module_specs/Zend_Ldap-API-Ldap.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17230 -->
<!-- Reviewed: no -->
<sect3 id="zend.ldap.api.reference.zend-ldap">
    <title>Zend_Ldap</title>

    <para>
        <classname>Zend_Ldap</classname> is the base interface into a <acronym>LDAP</acronym>
        server. It provides connection and binding methods as well as methods to operate on the
        <acronym>LDAP</acronym> tree.
    </para>

    <table id="zend.ldap.api.reference.zend-ldap.table">
        <title>Zend_Ldap API</title>

        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Method</entry>
                    <entry>Description</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>
                        <code>string filterEscape(string $str)</code>
                    </entry>
                    <entry>
                        Escapes a value to be used in a <acronym>LDAP</acronym> filter according to
                        <acronym>RFC</acronym> 2254. This method is <emphasis>deprecated</emphasis>, please use
                        <methodname>Zend_Ldap_Filter_Abstract::escapeValue()</methodname>
                        instead.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>boolean explodeDn($dn, array &amp;$keys = null, array &amp;$vals = null)</code>
                    </entry>
                    <entry>
                        Checks if a given DN <varname>$dn</varname> is malformed. If
                        <varname>$keys</varname> or <varname>$keys</varname> and <varname>$vals</varname> are
                        given, these arrays will be filled with the appropriate DN keys and
                        values. This method is <emphasis>deprecated</emphasis>, please use
                        <methodname>Zend_Ldap_Dn::checkDn()</methodname> instead.
                    </entry>
                </row>
                <row>
                    <entry><code>__construct($options)</code></entry>
                    <entry>
                        Constructor. The <varname>$options</varname> parameter is optional
                        and can be set to an array or a <classname>Zend_Config</classname> instance.
                        If no options are provided at instantiation, the connection
                        parameters must be passed to the instance using
                        <methodname>Zend_Ldap::setOptions()</methodname>. The allowed options are
                        specified in <link
                            linkend="zend.ldap.api.configuration.table">Zend_Ldap
                            Options</link>
                    </entry>
                </row>
                <row>
                    <entry><code>resource getResource()</code></entry>
                    <entry>Returns the raw <acronym>LDAP</acronym> extension (ext/ldap) resource.</entry>
                </row>
                <row>
                    <entry><code>integer getLastErrorCode()</code></entry>
                    <entry>
                        Returns the <acronym>LDAP</acronym> error number of the last <acronym>LDAP</acronym>
                        command.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>string getLastError(integer &amp;$errorCode, array &amp;$errorMessages)</code>
                    </entry>
                    <entry>
                        Returns the <acronym>LDAP</acronym> error message of the last <acronym>LDAP</acronym> command. The
                        optional <varname>$errorCode</varname> parameter is set to the <acronym>LDAP</acronym> error
                        number when given. The optional <varname>$errorMessages</varname> array
                        will be filled with the raw error messages when given. The various
                        <acronym>LDAP</acronym> error retrieval functions can return different things, so they
                        are all collected if <varname>$errorMessages</varname> is given.
                    </entry>
                </row>
                <row>
                    <entry><code>Zend_Ldap setOptions($options)</code></entry>
                    <entry>
                        Sets the <acronym>LDAP</acronym> connection and binding parameters.
                        <varname>$options</varname> can be an array or an instance of
                        <classname>Zend_Config</classname>. The allowed options are specified in
                        <link
                            linkend="zend.ldap.api.configuration.table">Zend_Ldap Options</link>
                    </entry>
                </row>
                <row>
                    <entry><code>array getOptions()</code></entry>
                    <entry>
                        Returns the current connection and binding
                        parameters.
                    </entry>
                </row>
                <row>
                    <entry><code>string getBaseDn()</code></entry>
                    <entry>
                        Returns the base DN this <acronym>LDAP</acronym> connection is bound
                        to.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>string getCanonicalAccountName(string $acctname, integer $form)</code>
                    </entry>
                    <entry>
                        Returns the canonical account name of the given account name
                        <varname>$acctname</varname>. <varname>$form</varname> specifies the <link
                            linkend="zend.ldap.using.theory-of-operation.account-name-canonicalization.table">format</link>
                        into which the account name is canonicalized. See <link
                            linkend="zend.ldap.introduction.theory-of-operations.account-name-canonicalization">Account Name Canonicalization</link>
                        for more details.
                    </entry>
                </row>
                <row>
                    <entry><code>Zend_Ldap disconnect()</code></entry>
                    <entry>
                        Disconnects the Zend_Ldap instance from the <acronym>LDAP</acronym>
                        server.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap connect(string $host, integer $port, boolean $useSsl, boolean $useStartTls)</code>
                    </entry>
                    <entry>
                        Connects the Zend_Ldap instance to the given <acronym>LDAP</acronym> server.
                        All parameters are optional and will be taken from the <acronym>LDAP</acronym>
                        connection and binding parameters passed to the instance via the
                        construtor or via <methodname>Zend_Ldap::setOptions()</methodname> when set to
                        <constant>NULL</constant>.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap bind(string $username, string $password)</code>
                    </entry>
                    <entry>
                        Authenticates <varname>$username</varname> with
                        <varname>$password</varname> at the <acronym>LDAP</acronym> server. If both paramaters are
                        omitted the binding will be carried out with the credentials given
                        in the connection and binding parameters. If no credentials are
                        given in the connection and binding parameters an anonymous bind
                        will be performed. Note that this requires anonymous binds to be
                        allowed on the <acronym>LDAP</acronym> server. An empty string <code>''</code> can be
                        passed as <varname>$password</varname> together with a username if, and
                        only if, <code>allowEmptyPassword</code> is set to
                        <constant>TRUE</constant> in the connection and binding parameters.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap_Collection search(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array $attributes, string $sort, string $collectionClass)</code>
                    </entry>
                    <entry>
                        Searches the <acronym>LDAP</acronym> tree with the given <varname>$filter</varname>
                        and the given search parameters.
                        <variablelist>
                            <varlistentry>
                                <term><code>string|Zend_Ldap_Filter_Abstract
                                $filter</code></term>

                                <listitem>
                                    <para>
                                        The filter string to be used in the search, e.g.
                                        <code>(objectClass=posixAccount)</code>.
                                    </para>
                                </listitem>
                            </varlistentry>

                            <varlistentry>
                                <term><code>string|Zend_Ldap_Dn $basedn</code></term>

                                <listitem>
                                    <para>
                                        The search base for the search. If omitted or
                                        <constant>NULL</constant>, the <code>baseDn</code> from the
                                        connection and binding parameters is used.
                                    </para>
                                </listitem>
                            </varlistentry>

                            <varlistentry>
                                <term><code>integer $scope</code></term>

                                <listitem>
                                    <para>
                                        The search scope.
                                        <constant>Zend_Ldap::SEARCH_SCOPE_SUB</constant> searches the
                                        complete subtree including the <varname>$baseDn</varname> node.
                                        <constant>Zend_Ldap::SEARCH_SCOPE_ONE</constant> restricts search
                                        to one level below <varname>$baseDn</varname>.
                                        <constant>Zend_Ldap::SEARCH_SCOPE_BASE</constant> restricts search
                                        to the <varname>$baseDn</varname> itself; this can be used to
                                        efficiently retrieve a single entry by its DN. The default
                                        value is
                                        <constant>Zend_Ldap::SEARCH_SCOPE_SUB</constant>.
                                    </para>
                                </listitem>
                            </varlistentry>

                            <varlistentry>
                                <term><code>array $attributes</code></term>

                                <listitem>
                                    <para>
                                        Specifies the attributes contained in the
                                        returned entries. To include all possible attributes (ACL
                                        restrictions can disallow certain attribute to be retrieved
                                        by a given user) pass either an empty array
                                        <methodname>array()</methodname> or <code>array('*')</code> to the
                                        method. On some <acronym>LDAP</acronym> servers you can retrieve special
                                        internal attributes by passing <code>array('*', '+')</code>
                                        to the method.
                                    </para>
                                </listitem>
                            </varlistentry>

                            <varlistentry>
                                <term><code>string $sort</code></term>

                                <listitem>
                                    <para>
                                        If given the result collection will be sorted
                                        after the attribute <varname>$sort</varname>. Results can only be
                                        sorted after one single attribute as this parameter uses
                                        the ext/ldap function <methodname>ldap_sort()</methodname>.
                                    </para>
                                </listitem>
                            </varlistentry>

                            <varlistentry>
                                <term><code>string $collectionClass</code></term>

                                <listitem>
                                    <para>
                                        If given the result will be wrapped in an object
                                        of type <varname>$collectionClass</varname>. By default an object
                                        of type <classname>Zend_Ldap_Collection</classname> will be returned.
                                        The custom class must extend
                                        <classname>Zend_Ldap_Collection</classname> and will be passed a
                                        <classname>Zend_Ldap_Collection_Iterator_Default</classname> on
                                        instantiation.
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>integer count(string|Zend_Ldap_Filter_Abstract
                        $filter, string|Zend_Ldap_Dn $basedn, integer
                        $scope)</code>
                    </entry>
                    <entry>
                        Counts the elements returned by the given search parameters.
                        See <methodname>Zend_Ldap::search()</methodname> for a detailed description of
                        the method parameters.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>integer countChildren(string|Zend_Ldap_Dn
                        $dn)</code>
                    </entry>
                    <entry>
                        Counts the direct descendants (children) of the entry
                        identified by the given <varname>$dn</varname>.
                    </entry>
                </row>
                <row>
                    <entry><code>boolean exists(string|Zend_Ldap_Dn $dn)</code></entry>
                    <entry>
                        Checks whether the entry identified by the given
                        <varname>$dn</varname> exists.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>array searchEntries(string|Zend_Ldap_Filter_Abstract
                        $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array
                        $attributes, string $sort)</code>
                    </entry>
                    <entry>
                        Performs a search operation and returns the result as an <acronym>PHP</acronym>
                        array. This is essentially the same method as
                        <methodname>Zend_Ldap::search()</methodname> except for the return type. See
                        <methodname>Zend_Ldap::search()</methodname> for a detailed description of the
                        method parameters.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>array getEntry(string|Zend_Ldap_Dn $dn, array
                        $attributes, boolean $throwOnNotFound)</code>
                    </entry>
                    <entry>
                        Retrieves the <acronym>LDAP</acronym> entry identified by <varname>$dn</varname> with
                        the attributes specified in <varname>$attributes</varname>. If
                        <varname>$attributes</varname> is ommitted, all attributes
                        (<methodname>array()</methodname>) are included in the result.
                        <varname>$throwOnNotFound</varname> is <constant>FALSE</constant> by default, so
                        the method will return <constant>NULL</constant> if the specified entry
                        cannot be found. If set to <constant>TRUE</constant>, a
                        <classname>Zend_Ldap_Exception</classname> will be thrown instead.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>void prepareLdapEntryArray(array
                        &amp;$entry)</code> </emphasis>
                    </entry>
                    <entry>
                        Bereitet ein Array für die Verwendung in Modifikations Operationen von
                        <acronym>LDAP</acronym> vor. Diese Methode muß nicht von Endbenutzern
                        aufgerufen werden da Sie implizit bei jeder Methode die Daten verändert
                        aufgerufen wird.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap add(string|Zend_Ldap_Dn $dn, array
                        $entry)</code>
                    </entry>
                    <entry>
                        Fügt den Eintrag der durch <varname>$dn</varname> mit seinen
                        <varname>$entry</varname> identifiziert wird im <acronym>LDAP</acronym>
                        Baum hinzu. Wirft eine <classname>Zend_Ldap_Exception</classname> wenn der
                        Eintrag nicht hinzugefügt werden konnte.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap update(string|Zend_Ldap_Dn $dn, array
                        $entry)</code>
                    </entry>
                    <entry>
                        Aktualisiert den Eintrag der durch <varname>$dn</varname> mit seinen
                        <varname>$entry</varname> Attributen identifiziert wird im
                        <acronym>LDAP</acronym> Baum. Wirft eine
                        <classname>Zend_Ldap_Exception</classname> wenn der Eintrag nicht geändert
                        werden konnte.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap save(string|Zend_Ldap_Dn $dn, array
                        $entry)</code>
                    </entry>
                    <entry>
                        Speichert den Eintrag der durch <varname>$dn</varname> mit seinen
                        <varname>$entry</varname> Attributen identifiziert wird im
                        <acronym>LDAP</acronym> Baum. Wirft eine
                        <classname>Zend_Ldap_Exception</classname> wenn der Eintrag nicht
                        gespeichert werden konnte. Diese Methode wählt durch eine Suche im
                        <acronym>LDAP</acronym> Baum ob der Eintrag hinzugefügt oder aktualisiert
                        wird.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap delete(string|Zend_Ldap_Dn $dn, boolean
                        $recursively)</code>
                    </entry>
                    <entry>
                        Löscht den Eintrag der durch <varname>$dn</varname> identifiziert wird vom
                        <acronym>LDAP</acronym> Baum. Wirft eine
                        <classname>Zend_Ldap_Exception</classname> Exception wenn der Eintrag nicht
                        gelöscht werden kann. <varname>$recursively</varname> ist standardmäßig
                        <constant>FALSE</constant>. Auf <constant>TRUE</constant> gesetzt wird
                        das Löschen rekursiv durchgeführt und löscht effektiver Weise den kompletten
                        Unterbaum. Das Löschen wird fehlschlagen wenn
                        <varname>$recursively</varname> <constant>FALSE</constant> ist und der
                        <varname>$dn</varname> Eintrag kein Blatteintrag ist.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap moveToSubtree(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively, boolean
                        $alwaysEmulate)</code>
                    </entry>
                    <entry>
                        Verschiebt den Eintrag der von <varname>$from</varname> identifiziert wird
                        auf einen Ort nach <varname>$to</varname> wobei sein <acronym>RDN</acronym>
                        unverändert bleibt. <varname>$recursively</varname> spezifiziert ob die
                        Operation rekursiv ausgeführt wird (standardmäßig
                        <constant>FALSE</constant>) so dass der Eintrag <varname>$from</varname> und
                        alle seine Untereinträge verschoben werden. Das Verschieben wird
                        fehlschlagen wenn <varname>$recursively</varname> <constant>FALSE</constant>
                        ist und der Eintrag <varname>$from</varname> kein Blatteintrag ist.
                        <varname>$alwaysEmulate</varname> kontrolliert ob die ext/ldap Funktion
                        <methodname>ldap_rename()</methodname> 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
                        <constant>TRUE</constant> gesetzt wird immer eine emulierte Rename Operation
                        verwendet.
                        <note>
                            <para>Alle Verschiebe-Operationen werden ausgeführt indem die
                            betreffenden Einträge im <acronym>LDAP</acronym> Baum kopiert und
                            anschließend gelöscht werden. Diese Operationen sind nicht
                            <emphasis>atomar</emphasis> so dass Fehler wärend der Operation zu einem
                            <emphasis>inkonsistenten</emphasis> Status am <acronym>LDAP</acronym>
                            Server führen. Das selbe gilt auch für alle rekursiven Operationen. Auch
                            diese sind in keiner Weise atomar. Man sollte das immer beachten.
                        </para>
                    </note></entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap move(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively, boolean
                        $alwaysEmulate)</code>
                    </entry>
                    <entry>
                        Das ist ein Alias für <methodname>Zend_Ldap::rename()</methodname>.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap rename(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively, boolean
                        $alwaysEmulate)</code>
                    </entry>
                    <entry>
                        Benennt den Eintrag der von <varname>$from</varname> bis
                        <varname>$to</varname> identifiziert wird um.
                        <varname>$recursively</varname> spezifiziert ob die Operation rekursiv
                        durchgeführt werden soll (standardmäßig <constant>FALSE</constant>) so das
                        der Eintrag <varname>$from</varname> und alle seine Abhängigkeiten
                        verschoben werden. Das Umbenennen wird fehlschlagen wenn
                        <varname>$recursively</varname> <constant>FALSE</constant> ist und der
                        Eintrag <varname>$from</varname> kein Blatteintrag ist.
                        <varname>$alwaysEmulate</varname> kontrolliert ob die ext/ldap Funktion
                        <methodname>ldap_rename()</methodname> 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
                        <constant>TRUE</constant> gesetzt wird immer die emulierte rename
                        Operation verwendet.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap copyToSubtree(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively)</code>
                    </entry>
                    <entry>
                        Kopiert den Eintrag der von <varname>$from</varname> bis zu einem Ort
                        unterhalb von <varname>$to</varname> identifiziert wird und lässt dessen
                        <acronym>RDN</acronym> unverändert. <varname>$recursively</varname>
                        spezifiziert ob die Operation rekursiv durchgeführt werden soll
                        (standardmäßig <constant>FALSE</constant>) so das der Eintrag
                        <varname>$from</varname> und alle seine Abhängigkeiten kopiert werden.
                        Das Kopieren wird fehlschlagen wenn <varname>$recursively</varname>
                        <constant>FALSE</constant> ist und der Eintrag <varname>$from</varname>
                        kein Blatteintrag ist.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap copy(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively)</code>
                    </entry>
                    <entry>
                        Kopiert den Eintrag der von <varname>$from</varname> bis
                        <varname>$to</varname> identifiziert wird. <varname>$recursively</varname>
                        spezifiziert ob die Operation rekursiv durchgeführt werden soll
                        (standardmäßig <constant>FALSE</constant>) so das der Eintrag
                        <varname>$from</varname> und alle seine Abhängigkeiten kopiert werden.
                        Das Kopieren wird fehlschlagen wenn <varname>$recursively</varname>
                        <constant>FALSE</constant> ist und der Eintrag <varname>$from</varname>
                        kein Blatteintrag ist.
                    </entry>
                </row>
                <row>
                    <entry>
                        <code>Zend_Ldap_Node getNode(string|Zend_Ldap_Dn
                        $dn)</code>
                    </entry>
                    <entry>
                        Gibt den <varname>$dn</varname> Eintrag zurück der in einem
                        <classname>Zend_Ldap_Node</classname> gewrappt ist.
                    </entry>
                </row>
                <row>
                    <entry><code>Zend_Ldap_Node getBaseNode()</code></entry>
                    <entry>
                        Gibt den Eintrag für den Basis DN <varname>$baseDn</varname> zurück
                        der in einer <classname>Zend_Ldap_Node</classname> gewrappt ist.
                    </entry>
                </row>
                <row>
                    <entry><code>Zend_Ldap_Node_RootDse getRootDse()</code></entry>
                    <entry>Gibt den RootDSE für den aktuellen Server zurück.</entry>
                </row>
                <row>
                    <entry><code>Zend_Ldap_Node_Schema getSchema()</code></entry>
                    <entry>
                        Gibt das <acronym>LDAP</acronym> Schema für den aktuellen Server zurück.
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <sect4 id="zend.ldap.api.reference.zend-ldap.zend-ldap-collection">
        <title>Zend_Ldap_Collection</title>

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

        <table id="zend.ldap.api.reference.zend-ldap.zend-ldap-collection.table">
            <title>API für Zend_Ldap_Collection</title>

            <tgroup cols="2">
            <thead>
                <row>
                    <entry>Methode</entry>
                    <entry>Beschreibung</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>
                        <code>__construct(Zend_Ldap_Collection_Iterator_Interface
                        $iterator)</code>
                    </entry>
                    <entry>
                        Constructor. Der Constructor muß von einem
                        <classname>Zend_Ldap_Collection_Iterator_Interface</classname> angeboten
                        werden welches die echte Iteration der Resultate durchführt.
                        <classname>Zend_Ldap_Collection_Iterator_Default</classname> ist die
                        standardmäßige Implementation für die Interation durch ext/ldap Ergebnisse.
                    </entry>
                </row>
                <row>
                    <entry><code>boolean close()</code></entry>
                    <entry>
                        Schließt den internen Iterator. Wird auch im Destructor aufgerufen.
                    </entry>
                </row>
                <row>
                    <entry><code>array toArray()</code></entry>
                    <entry>Gibt alle Einträge als Array zurück.</entry>
                </row>
                <row>
                    <entry><code>array getFirst()</code></entry>
                    <entry>
                        Gibt den ersten Eintrag der Collection zurück, oder <constant>NULL</constant> wenn
                        die Collection leer ist.
                    </entry>
                </row>
            </tbody></tgroup>
        </table>
    </sect4>
</sect3>