<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.ldap.usage">
    <title>Usage Scenarios</title>

    <sect2 id="zend.ldap.usage.authentication">
        <title>Authentication scenarios</title>

        <sect3 id="zend.ldap.usage.authentication.openldap">
            <title>OpenLDAP</title>
            <para/>
        </sect3>

        <sect3 id="zend.ldap.usage.authentication.activedirectory">
            <title>ActiveDirectory</title>
            <para/>
        </sect3>
    </sect2>

    <sect2 id="zend.ldap.usage.basic">
        <title>Basic CRUD operations</title>

        <sect3 id="zend.ldap.usage.basic.retrieve">
            <title>Retrieving data from the LDAP</title>

            <example id="zend.ldap.usage.basic.retrieve.dn">
                <title>Getting an entry by its DN</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$hm = $ldap->getEntry('cn=Hugo Müller,ou=People,dc=my,dc=local');
/*
$hm is an array of the following structure
array(
    'dn'          => 'cn=Hugo Müller,ou=People,dc=my,dc=local',
    'cn'          => array('Hugo Müller'),
    'sn'          => array('Müller'),
    'objectclass' => array('inetOrgPerson', 'top'),
    ...
)
*/
]]></programlisting>
            </example>

            <example id="zend.ldap.usage.basic.retrieve.exists">
                <title>Check for the existence of a given DN</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$isThere = $ldap->exists('cn=Hugo Müller,ou=People,dc=my,dc=local');
]]></programlisting>
            </example>

            <example id="zend.ldap.usage.basic.retrieve.counting-children">
                <title>Count children of a given DN</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$childrenCount = $ldap->countChildren(
                            'cn=Hugo Müller,ou=People,dc=my,dc=local');
]]></programlisting>
            </example>

            <example id="zend.ldap.usage.basic.retrieve.search">
                <title>Searching the LDAP tree</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$result = $ldap->search('(objectclass=*)',
                        'ou=People,dc=my,dc=local',
                        Zend_Ldap_Ext::SEARCH_SCOPE_ONE);
foreach ($result as $item) {
    echo $item["dn"] . ': ' . $item['cn'][0] . PHP_EOL;
}
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.ldap.usage.basic.add">
            <title>Adding data to the LDAP</title>

            <example>
                <title>Add a new entry to the LDAP</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$entry = array();
Zend_Ldap_Attribute::setAttribute($entry, 'cn', 'Hans Meier');
Zend_Ldap_Attribute::setAttribute($entry, 'sn', 'Meier');
Zend_Ldap_Attribute::setAttribute($entry, 'objectClass', 'inetOrgPerson');
$ldap->add('cn=Hans Meier,ou=People,dc=my,dc=local', $entry);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.ldap.usage.basic.delete">
            <title>Deleting from the LDAP</title>

            <example>
                <title>Delete an existing entry from the LDAP</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$ldap->delete('cn=Hans Meier,ou=People,dc=my,dc=local');
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.ldap.usage.basic.update">
            <title>Updating the LDAP</title>

            <example>
                <title>Update an existing entry on the LDAP</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$hm = $ldap->getEntry('cn=Hugo Müller,ou=People,dc=my,dc=local');
Zend_Ldap_Attribute::setAttribute($hm, 'mail', 'mueller@my.local');
Zend_Ldap_Attribute::setPassword($hm,
                                 'newPa$$w0rd',
                                 Zend_Ldap_Attribute::PASSWORD_HASH_SHA1);
$ldap->update('cn=Hugo Müller,ou=People,dc=my,dc=local', $hm);
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.ldap.usage.extended">
        <title>Extended operations</title>

        <sect3 id="zend.ldap.usage.extended.copy-and-move">
            <title>Copy and move entries in the LDAP</title>

            <example id="zend.ldap.usage.extended.copy-and-move.copy">
                <title>Copy a LDAP entry recursively with all its descendants</title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$ldap->copy('cn=Hugo Müller,ou=People,dc=my,dc=local',
            'cn=Hans Meier,ou=People,dc=my,dc=local',
            true);
]]></programlisting>
            </example>

            <example id="zend.ldap.usage.extended.copy-and-move.move-to-subtree">
                <title>
                    Move a LDAP entry recursively with all its descendants to a different subtree
                </title>

                <programlisting language="php"><![CDATA[
$options = array(/* ... */);
$ldap = new Zend_Ldap($options);
$ldap->bind();
$ldap->moveToSubtree('cn=Hugo Müller,ou=People,dc=my,dc=local',
                     'ou=Dismissed,dc=my,dc=local',
                     true);
]]></programlisting>
            </example>
        </sect3>
    </sect2>
</sect1>
