<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: bundled, external -->

 <reference id="ref.ldap">
  <title>LDAP Functions</title>
  <titleabbrev>LDAP</titleabbrev>

  <partintro>
   <section id="ldap.intro">
    &reftitle.intro;
    <para>
     LDAP is the Lightweight Directory Access Protocol, and is a
     protocol used to access "Directory Servers". The Directory is a
     special kind of database that holds information in a tree
     structure.  
    </para>
    <para> 
     The concept is similar to your hard disk directory structure,
     except that in this context, the root directory is "The world"
     and the first level subdirectories are "countries". Lower levels
     of the directory structure contain entries for companies,
     organisations or places, while yet lower still we find directory
     entries for people, and perhaps equipment or documents.
    </para>
    <para>
     To refer to a file in a subdirectory on your hard disk, you might
     use something like:
    </para>
    <literallayout>
     /usr/local/myapp/docs
    </literallayout>
    <para>
     The forwards slash marks each division in the reference, and the
     sequence is read from left to right.
    </para>
    <para> 
     The equivalent to the fully qualified file reference in LDAP is
     the "distinguished name", referred to simply as "dn". An example
     dn might be:
    </para>
    <literallayout>
     cn=John Smith,ou=Accounts,o=My Company,c=US
    </literallayout>
    <para>
     The comma marks each division in the reference, and the sequence
     is read from right to left. You would read this dn as:
    </para>
    <literallayout>
     country = US
     organization = My Company
     organizationalUnit = Accounts
     commonName = John Smith
    </literallayout>
    <para>
     In the same way as there are no hard rules about how you organise
     the directory structure of a hard disk, a directory server
     manager can set up any structure that is meaningful for the
     purpose. However, there are some conventions that are used. The
     message is that you can not write code to access a directory
     server unless you know something about its structure, any more
     than you can use a database without some knowledge of what is
     available.
    </para>
    <para>
     Lots of information about LDAP can be found at
    </para>

    <itemizedlist>
     <listitem>
      <para>
       <ulink url="&url.ldap.netscape;">Mozilla</ulink>
      </para>
     </listitem>
     <listitem>
      <para>
       <ulink url="&url.ldap.openldap;">OpenLDAP Project</ulink>
      </para>
     </listitem>
    </itemizedlist>

    <para>    
     The Netscape SDK contains a helpful
     <ulink url="&url.ldap.netscape.sdk.docs;">Programmer's Guide</ulink> in
     HTML format.
    </para>
   </section>

   <section id="ldap.requirements">
    &reftitle.required;
    <para>
     You will need to get and compile LDAP client libraries from either
     <ulink url="&url.ldap.openldap.source;">OpenLDAP</ulink> or <ulink
     url="&url.ldap.bind9;">Bind9.net</ulink> in order to compile PHP with
     LDAP support.
<!--
     The other links are dead.. (7/7/2005)
     So were those Netscape links - updated netscape.sdk link to mozilla.org
     now. Also added new entity, url.ldap.bind9, which offers a win32 binary
     amongst other things (31/7/2005)

     either the University of Michigan <ulink url="&url.ldap.mt;">
     ldap-3.3 package</ulink>, <ulink url="&url.ldap.netscape.sdk;"> Netscape
     Directory SDK 3.0</ulink> or <ulink url="&url.ldap.openldap.source;">
     OpenLDAP</ulink> to compile PHP with LDAP support.
-->
    </para>
   </section>

  &reference.ldap.configure;

   &reference.ldap.ini;

   <section id="ldap.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.ldap.constants;

   <section id="ldap.examples">
    &reftitle.examples;
    <para>
     Retrieve information for all entries where the surname starts
     with "S" from a directory server, displaying an extract with
     name and email address.
    </para>

    <example>
     <title>LDAP search example</title>
     <programlisting role="php">
<![CDATA[
<?php
// basic sequence with LDAP is connect, bind, search, interpret search
// result, close connection

echo "<h3>LDAP query test</h3>";
echo "Connecting ...";
$ds=ldap_connect("localhost");  // must be a valid LDAP server!
echo "connect result is " . $ds . "<br />";

if ($ds) { 
    echo "Binding ..."; 
    $r=ldap_bind($ds);     // this is an "anonymous" bind, typically
                           // read-only access
    echo "Bind result is " . $r . "<br />";

    echo "Searching for (sn=S*) ...";
    // Search surname entry
    $sr=ldap_search($ds, "o=My Company, c=US", "sn=S*");  
    echo "Search result is " . $sr . "<br />";

    echo "Number of entires returned is " . ldap_count_entries($ds, $sr) . "<br />";

    echo "Getting entries ...<p>";
    $info = ldap_get_entries($ds, $sr);
    echo "Data for " . $info["count"] . " items returned:<p>";

    for ($i=0; $i<$info["count"]; $i++) {
        echo "dn is: " . $info[$i]["dn"] . "<br />";
        echo "first cn entry is: " . $info[$i]["cn"][0] . "<br />";
        echo "first email entry is: " . $info[$i]["mail"][0] . "<br /><hr />";
    }

    echo "Closing connection";
    ldap_close($ds);

} else {
    echo "<h4>Unable to connect to LDAP server</h4>";
}
?>
]]>
     </programlisting>
    </example>
   </section>

   <section id="ldap.using">
    <title>Using the PHP LDAP calls</title>
    <para>
     Before you can use the LDAP calls you will need to know ..

    <itemizedlist>
     <listitem>
      <para>
       The name or address of the directory server you will use
      </para>
     </listitem>
     <listitem>
      <para>
       The "base dn" of the server (the part of the world directory
       that is held on this server, which could be "o=My
       Company,c=US")
      </para>
     </listitem>
     <listitem>
      <para>
       Whether you need a password to access the server (many servers
       will provide read access for an "anonymous bind" but require a
       password for anything else)
      </para>
     </listitem>
    </itemizedlist></para>

     <para>
      The typical sequence of LDAP calls you will make in an
      application will follow this pattern:
<literallayout>
  ldap_connect()    // establish connection to server
     |
  ldap_bind()       // anonymous or authenticated "login"
     |
  do something like search or update the directory
  and display the results
     |
  ldap_close()      // "logout"
</literallayout></para>
   </section>
  </partintro>

&reference.ldap.functions;

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->