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

<?xml version="1.0" encoding="utf-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.ldap.api" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>API overview</title>

    <sect2 id="zend.ldap.api.configuration">
        <title>Configuration / options</title>

        <para>
            The <classname>Zend_Ldap</classname> component accepts an array of options either
            supplied to the constructor or through the <methodname>setOptions()</methodname>
            method. The permitted options are as follows:
        </para>

        <table id="zend.ldap.api.configuration.table">
            <title>Zend_Ldap Options</title>

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

                <tbody>
                    <row>
                        <entry><property>host</property></entry>

                        <entry>
                            The default hostname of <acronym>LDAP</acronym> server if not
                            supplied to <methodname>connect()</methodname> (also may be used
                            when trying to canonicalize usernames in
                            <methodname>bind()</methodname>).
                        </entry>
                    </row>

                    <row>
                        <entry><property>port</property></entry>

                        <entry>
                            Default port of <acronym>LDAP</acronym> server if not supplied to
                            <methodname>connect()</methodname>.
                        </entry>
                    </row>

                    <row>
                        <entry><property>useStartTls</property></entry>

                        <entry>
                            Whether or not the <acronym>LDAP</acronym> client should use
                            <acronym>TLS</acronym> (aka <acronym>SSLv2</acronym>) encrypted
                            transport. A value of <constant>TRUE</constant> is strongly favored
                            in production environments to prevent passwords from be transmitted in
                            clear text. The default value is <constant>FALSE</constant>, as servers
                            frequently require that a certificate be installed separately after
                            installation. The <emphasis>useSsl</emphasis> and
                            <emphasis>useStartTls</emphasis> options are mutually exclusive.
                            The <emphasis>useStartTls</emphasis> option should be favored
                            over <emphasis>useSsl</emphasis> but not all servers support
                            this newer mechanism.
                        </entry>
                    </row>

                    <row>
                        <entry><property>useSsl</property></entry>

                        <entry>
                            Whether or not the <acronym>LDAP</acronym> client should use
                            <acronym>SSL</acronym> encrypted transport. The
                            <emphasis>useSsl</emphasis> and <emphasis>useStartTls</emphasis>
                            options are mutually exclusive.
                        </entry>
                    </row>

                    <row>
                        <entry><property>username</property></entry>

                        <entry>
                            The default credentials username. Some servers require that this
                            be in DN form. This must be given in DN form if the
                            <acronym>LDAP</acronym> server requires a DN to bind and binding
                            should be possible with simple usernames.
                        </entry>
                    </row>

                    <row>
                        <entry><property>password</property></entry>

                        <entry>
                            The default credentials password (used only with username
                            above).
                        </entry>
                    </row>

                    <row>
                        <entry><property>bindRequiresDn</property></entry>

                        <entry>
                            If <constant>TRUE</constant>, this instructs
                            <classname>Zend_Ldap</classname> to retrieve the DN for the
                            account used to bind if the username is not
                            already in DN form. The default value is <constant>FALSE</constant>.
                        </entry>
                    </row>

                    <row>
                        <entry><property>baseDn</property></entry>

                        <entry>
                            The default base DN used for searching (e.g., for accounts).
                            This option is required for most account related operations and should
                            indicate the DN under which accounts are located.
                        </entry>
                    </row>

                    <row>
                        <entry><property>accountCanonicalForm</property></entry>

                        <entry>
                            A small integer indicating the form to which account names
                            should be canonicalized. See the <link
                                linkend="zend.ldap.introduction.theory-of-operations.account-name-canonicalization"><emphasis>Account
                                Name Canonicalization</emphasis></link>
                            section below.
                        </entry>
                    </row>

                    <row>
                        <entry><property>accountDomainName</property></entry>

                        <entry>
                            The <acronym>FQDN</acronym> domain for which the target
                            <acronym>LDAP</acronym> server is an authority (e.g., example.com).
                        </entry>
                    </row>

                    <row>
                        <entry><property>accountDomainNameShort</property></entry>

                        <entry>
                            The 'short' domain for which the target <acronym>LDAP</acronym> server
                            is an authority. This is usually used to specify the NetBIOS
                            domain name for Windows networks but may also be used by non-AD servers.
                        </entry>
                    </row>

                    <row>
                        <entry><property>accountFilterFormat</property></entry>

                        <entry>
                            The <acronym>LDAP</acronym> search filter used to search for accounts.
                            This string is a <ulink
                                url="http://php.net/sprintf"><methodname>sprintf()</methodname></ulink>
                            style expression that must contain one '<emphasis>%s</emphasis>' to
                            accommodate the username. The default value is
                            '<emphasis>(&amp;(objectClass=user)(sAMAccountName=%s))</emphasis>'
                            unless <emphasis>bindRequiresDn</emphasis> is set to
                            <constant>TRUE</constant>, in which case the default is
                            '<emphasis>(&amp;(objectClass=posixAccount)(uid=%s))</emphasis>'.
                            Users of custom schemas may need to change this option.
                        </entry>
                    </row>

                    <row>
                        <entry><property>allowEmptyPassword</property></entry>

                        <entry>
                            Some <acronym>LDAP</acronym> servers can be configured to accept an
                            empty string password as an anonymous bind. This behavior is almost
                            always undesirable. For this reason, empty passwords are explicitly
                            disallowed. Set this value to <constant>TRUE</constant> to allow an
                            empty string password to be submitted during the bind.
                        </entry>
                    </row>

                    <row>
                        <entry><property>optReferrals</property></entry>

                        <entry>
                            If set to <constant>TRUE</constant>, this option indicates to the
                            <acronym>LDAP</acronym> client that referrals should be followed.
                            The default value is <constant>FALSE</constant>.
                        </entry>
                    </row>

                    <row>
                        <entry><property>tryUsernameSplit</property></entry>

                        <entry>
                            If set to <constant>FALSE</constant>, this option indicates that the
                            given username should not be split at the first <emphasis>@</emphasis>
                            or <emphasis>\</emphasis> character to separate the username from
                            the domain during the binding-procedure. This allows the user to
                            use usernames that contain an <emphasis>@</emphasis> or
                            <emphasis>\</emphasis> character that do not
                            inherit some domain-information, e.g. using email-addresses for
                            binding. The default value is <constant>TRUE</constant>.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.ldap.api.reference">
        <title>API Reference</title>

        <note>
            <para>Method names in <emphasis>italics</emphasis> are static methods.</para>
        </note>

        <xi:include href="Zend_Ldap-API-Ldap.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Attribute.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Dn.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Filter.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Node.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Node-RootDse.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Node-Schema.xml" />
        <xi:include href="Zend_Ldap-API-Ldap-Ldif-Encoder.xml" />
    </sect2>
</sect1>