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

<?xml version="1.0" encoding="UTF-8"?>
<!-- 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><methodname>__construct($options)</methodname></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 <classname>Zend_Ldap</classname> 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 <classname>Zend_Ldap</classname> 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 constructor 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
                        parameters 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
                                        <methodname>array('*')</methodname> to the method. On some
                                        <acronym>LDAP</acronym> servers you can retrieve special
                                        internal attributes by passing
                                        <methodname>array('*', '+')</methodname> 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>
                        Prepare an array for the use in <acronym>LDAP</acronym> modification
                        operations. This method does not need to be called by the end-user
                        as it's implicitly called on every data modification
                        method.
                    </entry>
                </row>

                <row>
                    <entry>
                        <code>Zend_Ldap add(string|Zend_Ldap_Dn $dn, array
                        $entry)</code>
                    </entry>

                    <entry>
                        Adds the entry identified by <varname>$dn</varname> with its attributes
                        <varname>$entry</varname> to the <acronym>LDAP</acronym> tree. Throws a
                        <classname>Zend_Ldap_Exception</classname> if the entry could not be
                        added.
                    </entry>
                </row>

                <row>
                    <entry>
                        <code>Zend_Ldap update(string|Zend_Ldap_Dn $dn, array $entry)</code>
                    </entry>

                    <entry>
                        Updates the entry identified by <varname>$dn</varname> with its attributes
                        <varname>$entry</varname> to the <acronym>LDAP</acronym> tree. Throws a
                        <classname>Zend_Ldap_Exception</classname> if the entry could not be
                        modified.
                    </entry>
                </row>

                <row>
                    <entry>
                        <code>Zend_Ldap save(string|Zend_Ldap_Dn $dn, array $entry)</code>
                    </entry>

                    <entry>
                        Saves the entry identified by <varname>$dn</varname> with its attributes
                        <varname>$entry</varname> to the <acronym>LDAP</acronym> tree. Throws a
                        <classname>Zend_Ldap_Exception</classname> if the entry could not be saved.
                        This method decides by querying the <acronym>LDAP</acronym> tree if the
                        entry will be added or updated.
                    </entry>
                </row>

                <row>
                    <entry>
                        <code>Zend_Ldap delete(string|Zend_Ldap_Dn $dn, boolean $recursively)</code>
                    </entry>

                    <entry>
                        Deletes the entry identified by <varname>$dn</varname> from the
                        <acronym>LDAP</acronym> tree. Throws a
                        <classname>Zend_Ldap_Exception</classname> if the entry could not be
                        deleted. <varname>$recursively</varname> is <constant>FALSE</constant> by
                        default. If set to <constant>TRUE</constant> the deletion will be carried
                        out recursively and will effectively delete a complete subtree. Deletion
                        will fail if <varname>$recursively</varname> is <constant>FALSE</constant>
                        and the entry <varname>$dn</varname> is not a leaf entry.
                    </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>
                        Moves the entry identified by <varname>$from</varname> to a location below
                        <varname>$to</varname> keeping its <acronym>RDN</acronym> unchanged.
                        <varname>$recursively</varname> specifies if the operation will be
                        carried out recursively (<constant>FALSE</constant> by default) so that the
                        entry <varname>$from</varname> and all its descendants will be moved.
                        Moving will fail if <varname>$recursively</varname> is
                        <constant>FALSE</constant> and the entry <varname>$from</varname> is not a
                        leaf entry. <varname>$alwaysEmulate</varname> controls whether the ext/ldap
                        function <methodname>ldap_rename()</methodname> should be used if available.
                        This can only work for leaf entries and for servers and for ext/ldap
                        supporting this function. Set to <constant>TRUE</constant> to always use an
                        emulated rename operation.

                        <note>
                            <para>
                                All move-operations are carried out by copying and then deleting the
                                corresponding entries in the <acronym>LDAP</acronym> tree. These
                                operations are not <emphasis>atomic</emphasis> so that failures
                                during the operation will result in an
                                <emphasis>inconsistent</emphasis> state on the
                                <acronym>LDAP</acronym> server. The same is true for all recursive
                                operations. They also are by no means atomic. Please keep this in
                                mind.
                            </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>
                        This is an alias for <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>
                        Renames the entry identified by <varname>$from</varname> to
                        <varname>$to</varname>. <varname>$recursively</varname> specifies if the
                        operation will be carried out recursively (<constant>FALSE</constant> by
                        default) so that the entry <varname>$from</varname> and all its
                        descendants will be moved. Moving will fail if
                        <varname>$recursively</varname> is <constant>FALSE</constant> and the entry
                        <varname>$from</varname> is not a leaf entry.
                        <varname>$alwaysEmulate</varname> controls whether the ext/ldap function
                        <methodname>ldap_rename()</methodname> should be used if available. This can
                        only work for leaf entries and for servers and for ext/ldap supporting this
                        function. Set to <constant>TRUE</constant> to always use an emulated rename
                        operation.
                    </entry>
                </row>

                <row>
                    <entry>
                        <code>Zend_Ldap copyToSubtree(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively)</code>
                    </entry>

                    <entry>
                        Copies the entry identified by <varname>$from</varname> to a location below
                        <varname>$to</varname> keeping its <acronym>RDN</acronym> unchanged.
                        <varname>$recursively</varname> specifies if the operation will be
                        carried out recursively (<constant>FALSE</constant> by default) so that the
                        entry <varname>$from</varname> and all its descendants will be copied.
                        Copying will fail if <varname>$recursively</varname> is
                        <constant>FALSE</constant> and the entry <varname>$from</varname> is not a
                        leaf entry.
                    </entry>
                </row>

                <row>
                    <entry>
                        <code>Zend_Ldap copy(string|Zend_Ldap_Dn $from,
                        string|Zend_Ldap_Dn $to, boolean $recursively)</code>
                    </entry>

                    <entry>
                        Copies the entry identified by <varname>$from</varname> to
                        <varname>$to</varname>. <varname>$recursively</varname> specifies if the
                        operation will be carried out recursively (<constant>FALSE</constant> by
                        default) so that the entry <varname>$from</varname> and all its
                        descendants will be copied. Copying will fail if
                        <varname>$recursively</varname> is <constant>FALSE</constant> and the entry
                        <varname>$from</varname> is not a leaf entry.
                    </entry>
                </row>

                <row>
                    <entry><code>Zend_Ldap_Node getNode(string|Zend_Ldap_Dn $dn)</code></entry>

                    <entry>
                        Returns the entry <varname>$dn</varname> wrapped in a
                        <classname>Zend_Ldap_Node</classname>.
                    </entry>
                </row>

                <row>
                    <entry><code>Zend_Ldap_Node getBaseNode()</code></entry>

                    <entry>
                        Returns the entry for the base DN <varname>$baseDn</varname>
                        wrapped in a <classname>Zend_Ldap_Node</classname>.
                    </entry>
                </row>

                <row>
                    <entry><code>Zend_Ldap_Node_RootDse getRootDse()</code></entry>
                    <entry>Returns the RootDSE for the current server.</entry>
                </row>

                <row>
                    <entry><code>Zend_Ldap_Node_Schema getSchema()</code></entry>
                    <entry>
                        Returns the <acronym>LDAP</acronym> schema for the current server.
                    </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> implements <code>Iterator</code> to
            allow for item traversal using <methodname>foreach()</methodname> and
            <code>Countable</code> to be able to respond to <methodname>count()</methodname>. With
            its protected <methodname>_createEntry()</methodname> method it provides a simple
            extension point for developers needing custom result objects.
        </para>

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

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Method</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>
                            <code>__construct(Zend_Ldap_Collection_Iterator_Interface
                            $iterator)</code>
                        </entry>

                        <entry>
                            Constructor. The constrcutor must be provided by a
                            <classname>Zend_Ldap_Collection_Iterator_Interface</classname> which
                            does the real result iteration.
                            <classname>Zend_Ldap_Collection_Iterator_Default</classname> is the
                            default implementation for iterating ext/ldap results.
                        </entry>
                    </row>

                    <row>
                        <entry><code>boolean close()</code></entry>

                        <entry>
                            Closes the internal iterator. This is also called in the destructor.
                        </entry>
                    </row>

                    <row>
                        <entry><code>array toArray()</code></entry>
                        <entry>Returns all entries as an array.</entry>
                    </row>

                    <row>
                        <entry><code>array getFirst()</code></entry>

                        <entry>
                            Returns the first entry in the collection or
                            <constant>NULL</constant> if the collection is empty.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect4>
</sect3>