CVS update: php3/doc/functions

Date: Sunday November 29, 1998 @ 5:19 Author: eschmid Update of /repository/php3/doc/functions In directory asf:/u2/tmp/cvs-serv14793/functions Modified Files: ldap.sgml Log Message: More notes from the annotated manual. Index: php3/doc/functions/ldap.sgml diff -c php3/doc/functions/ldap.sgml:1.23 php3/doc/functions/ldap.sgml:1.24 *** php3/doc/functions/ldap.sgml:1.23 Sat Nov 28 16:14:14 1998 --- php3/doc/functions/ldap.sgml Sun Nov 29 05:19:08 1998 *************** *** 209,222 **** <paramdef>array <parameter>entry</parameter></paramdef> </funcsynopsis> <para> ! returns true on success and false on error. ! </para><para> ! The ldap_add() function is used to add entries in the LDAP ! directory. The DN of the entry to be added is specified by ! dn. Array entry specifies the information about the entry. The ! values in the entries are indexed by individual attributes. In ! case of multiple values for an attribute, they are indexed using ! integers starting with 0. </para> <informalexample> <literallayout> --- 209,222 ---- <paramdef>array <parameter>entry</parameter></paramdef> </funcsynopsis> <para> ! returns true on success and false on error. ! </para><para> ! The <function>ldap_add</function> function is used to add entries ! in the LDAP directory. The DN of the entry to be added is ! specified by dn. Array entry specifies the information about the ! entry. The values in the entries are indexed by individual ! attributes. In case of multiple values for an attribute, they are ! indexed using integers starting with 0. </para> <informalexample> <literallayout> *************** *** 269,280 **** <paramdef>string <parameter>bind_password</parameter></paramdef> </funcsynopsis> <para> ! Binds to the LDAP directory with specified RDN and password. Returns ! true on success and false on error. <para> ! ldap_bind() does a bind operation on the directory. bind_rdn and ! bind_password are optional. If not specified, anonymous bind is ! attempted. </refsect1> </refentry> --- 269,280 ---- <paramdef>string <parameter>bind_password</parameter></paramdef> </funcsynopsis> <para> ! Binds to the LDAP directory with specified RDN and ! password. Returns true on success and false on error. <para> ! <function>ldap_bind</function> does a bind operation on the ! directory. bind_rdn and bind_password are optional. If not ! specified, anonymous bind is attempted. </refsect1> </refentry> *************** *** 318,331 **** <paramdef>int <parameter>port</parameter></paramdef> </funcsynopsis> <para> ! Returns a positive LDAP link identifier on success, or false on error. ! <para> ! ldap_connect() establishes a connection to a LDAP server on a specified ! <parameter>hostname</parameter> and <parameter>port</parameter>. ! Both the arguments are optional. If no arguments are ! specified then the link identifier of the already opened link will be ! returned. If only <parameter>hostname</parameter> is specified, then the ! port defaults to 389. </refsect1> </refentry> --- 318,333 ---- <paramdef>int <parameter>port</parameter></paramdef> </funcsynopsis> <para> ! Returns a positive LDAP link identifier on success, or false on ! error. ! <para> ! <function>ldap_connect</function> establishes a connection to a ! LDAP server on a specified <parameter>hostname</parameter> and ! <parameter>port</parameter>. Both the arguments are optional. If ! no arguments are specified then the link identifier of the ! already opened link will be returned. If only ! <parameter>hostname</parameter> is specified, then the port ! defaults to 389. </refsect1> </refentry> *************** *** 343,353 **** <paramdef>int <parameter>result_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns number of entries in the result or false on error. <para> ! ldap_count_entries() returns the number of entries stored in the result ! of previous search operations. <parameter>result_identifier</parameter> ! identifies the internal ldap result. </refsect1> </refentry> --- 345,356 ---- <paramdef>int <parameter>result_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns number of entries in the result or false on error. <para> ! <function>ldap_count_entries</function> returns the number of ! entries stored in the result of previous search ! operations. <parameter>result_identifier</parameter> identifies ! the internal ldap result. </refsect1> </refentry> *************** *** 365,374 **** <paramdef>string <parameter>dn</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. ! <para> ! ldap_delete() function delete a particular entry in LDAP directory ! specified by dn. </refsect1> </refentry> --- 368,377 ---- <paramdef>string <parameter>dn</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. ! <para> ! <function>ldap_delete</function> function delete a particular ! entry in LDAP directory specified by dn. </refsect1> </refentry> *************** *** 385,392 **** <paramdef>string <parameter>dn</parameter></paramdef> </funcsynopsis> <para> ! ldap_dn2ufn() function is used to turn a DN into a more user-friendly ! form, stripping off type names. </refsect1> </refentry> --- 388,395 ---- <paramdef>string <parameter>dn</parameter></paramdef> </funcsynopsis> <para> ! <function>ldap_dn2ufn</function> function is used to turn a DN ! into a more user-friendly form, stripping off type names. </refsect1> </refentry> *************** *** 404,418 **** <paramdef>int <parameter>with_attrib</parameter></paramdef> </funcsynopsis> <para> ! ldap_explode_dn() function is used to split the a DN returned by ! <function>ldap_get_dn</function> and breaks it up into its component ! parts. Each part is known as Relative Distinguished Name, or RDN. ! <function>ldap_explode_dn</function> returns an array of all those ! components. <parameter>with_attrib</parameter> is used to request if ! the RDNs are returned with only values or their attributes as well. ! To get RDNs with the attributes (i.e. in attribute=value format) set ! <parameter>with_attrib</parameter> to 1 and to get only values set it ! to 0. </refsect1> </refentry> --- 407,422 ---- <paramdef>int <parameter>with_attrib</parameter></paramdef> </funcsynopsis> <para> ! <function>ldap_explode_dn</function> function is used to split ! the a DN returned by <function>ldap_get_dn</function> and breaks ! it up into its component parts. Each part is known as Relative ! Distinguished Name, or RDN. <function>ldap_explode_dn</function> ! returns an array of all those components. ! <parameter>with_attrib</parameter> is used to request if the RDNs ! are returned with only values or their attributes as well. To ! get RDNs with the attributes (i.e. in attribute=value format) set ! <parameter>with_attrib</parameter> to 1 and to get only values ! set it to 0. </refsect1> </refentry> *************** *** 431,447 **** <paramdef>int <parameter>ber_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns the first attribute in the entry on success and false on error. <para> ! Similar to reading entries, attributes are also read one ! by one from a particular entry. <function>ldap_first_attribute</function> returns the ! first attribute in the entry pointed by the entry identifier. Remaining ! attributes are retrieved by calling <function>ldap_next_attribute</function> successively. ! <parameter>ber_identifier</parameter> is the identifier to internal memory location pointer. It ! is passed by reference. The same <parameter>ber_identifier</parameter> is passed to the ! ldap_next_attribute() function, which modifies that pointer. ! <para> ! see also <function>ldap_get_attributes</function> </refsect1> </refentry> --- 435,455 ---- <paramdef>int <parameter>ber_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns the first attribute in the entry on success and false on ! error. <para> ! Similar to reading entries, attributes are also read one by one ! from a particular entry. ! <function>ldap_first_attribute</function> returns the first ! attribute in the entry pointed by the entry identifier. ! Remaining attributes are retrieved by calling ! <function>ldap_next_attribute</function> successively. ! <parameter>ber_identifier</parameter> is the identifier to ! internal memory location pointer. It is passed by reference. The ! same <parameter>ber_identifier</parameter> is passed to the ! ldap_next_attribute() function, which modifies that pointer. ! <para> ! see also <function>ldap_get_attributes</function> </refsect1> </refentry> *************** *** 459,474 **** <paramdef>int <parameter>result_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns the result entry identifier for the first entry on success and ! false on error. <para> ! Entries in the LDAP result are read sequentially using the ldap_first_entry() ! and ldap_next_entry() functions. ldap_first_entry() returns the entry ! identifier for first entry in the result. This entry identifier is then ! supplied to <function>lap_next_entry</function> routine to get successive e ! ntries from the result. ! <para> ! see also <function>ldap_get_entries</function>. </refsect1> </refentry> --- 467,485 ---- <paramdef>int <parameter>result_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns the result entry identifier for the first entry on ! success and false on error. <para> ! Entries in the LDAP result are read sequentially using the ! <function>ldap_first_entry</function> and ! <function>ldap_next_entry</function> ! functions. <function>ldap_first_entry</function> returns the ! entry identifier for first entry in the result. This entry ! identifier is then supplied to ! <function>lap_next_entry</function> routine to get successive ! entries from the result. ! <para> ! see also <function>ldap_get_entries</function>. </refsect1> </refentry> *************** *** 485,500 **** <paramdef>int <parameter>result_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. <para> ! ldap_free_result() frees up the memory allocated internally to store ! the result and pointed by the result_identifier. All result memory ! will be automatically freed when the script terminates. ! <para> ! Typically all the memory allocated for the ldap result gets freed at ! the end of the script. In case the script is making successive searches ! which return large result sets, ldap_free_result() could be called ! to keep the runtime memory usage by the script low. </refsect1> </refentry> --- 496,513 ---- <paramdef>int <parameter>result_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. <para> ! <function>ldap_free_result</function> frees up the memory ! allocated internally to store the result and pointed by the ! <parameter>result_identifier</parameter>. All result memory will ! be automatically freed when the script terminates. ! <para> ! Typically all the memory allocated for the ldap result gets freed ! at the end of the script. In case the script is making successive ! searches which return large result sets, ! <function>ldap_free_result</function> could be called to keep the ! runtime memory usage by the script low. </refsect1> </refentry> *************** *** 559,566 **** </programlisting> </example> ! see also <function>ldap_first_attribute</function> and ! <function>ldap_next_attribute</function> </refsect1> </refentry> --- 572,580 ---- </programlisting> </example> ! <para> ! see also <function>ldap_first_attribute</function> and ! <function>ldap_next_attribute</function> </refsect1> </refentry> *************** *** 611,617 **** follows. <para> The attribute index is converted to lowercase. (Attributes are ! case- insensitive for directory servers, but not when used as array indices) <informalexample> --- 625,631 ---- follows. <para> The attribute index is converted to lowercase. (Attributes are ! case-insensitive for directory servers, but not when used as array indices) <informalexample> *************** *** 630,637 **** </literallayout> </informalexample> ! see also <function>ldap_first_entry</function> ! and <function>ldap_next_entry</function> </refsect1> </refentry> --- 644,652 ---- </literallayout> </informalexample> ! <para> ! see also <function>ldap_first_entry</function> and ! <function>ldap_next_entry</function> </refsect1> </refentry> *************** *** 660,665 **** --- 675,693 ---- values can be found by indexing "count" in the resultant array. Individual values are accessed by integer index in the array. The first index is 0. + <para> + This call needs a <parameter>result_entry_identifier</parameter>, + so needs to be preceded by one of the ldap search calls and one + of the calls to get an individual entry. + <para> + You application will either be hard coded to look for certain + attributes (such as "surname" or "mail") or you will have to use + the <function>ldap_get_attributes</function> call to work out + what attributes exist for a given entry. + <para> + LDAP allows more than one entry for an attribute, so it can, for + example, store a number of email addresses for one person's + directory entry all labeled with the attribute "mail" <informalexample> <literallayout> *************** *** 669,674 **** --- 697,723 ---- </literallayout> </informalexample> + <example> + <title>List all values of the "mail" attribute for a + directory entry </title> + <programlisting role=php> + // $ds is a valid link identifier for a directory server + + // $sr is a valid search result from a prior call to + // one of the ldap directory search calls + + // $entry is a valid entry identifier from a prior call to + // one of the calls that returns a directory entry + + $values = ldap_get_values($ds, $entry,"mail"); + + echo $values["count"]." email addresses for this entry.&lt;p>"; + + for ($i=0; $i &lt; $values["count"]; $i++) + echo $values[$i]."&lt;br>"; + </programlisting> + </example> + </refsect1> </refentry> *************** *** 700,705 **** --- 749,755 ---- This call takes an optional fourth parameter which is an array of the attributes required. See <function>ldap_search</function> notes. + <example> <title>Produce a list of all organizational units of an organization </title> *************** *** 735,744 **** <paramdef>array <parameter>entry</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. ! <para> ! ldap_modify() function is used to modify the existing entries in the LDAP ! directory. The structure of the entry is same as in <function>ldap_add</function>. </refsect1> </refentry> --- 785,795 ---- <paramdef>array <parameter>entry</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. ! <para> ! <function>ldap_modify</function> function is used to modify the ! existing entries in the LDAP directory. The structure of the ! entry is same as in <function>ldap_add</function>. </refsect1> </refentry> *************** *** 757,771 **** <paramdef>int <parameter>ber_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns the next attribute in an entry on success and false on error. <para> ! ldap_next_attribute() is called to retrieve the attributes in an entry. ! The internal state of the pointer is maintained by the <parameter>ber_identifier</parameter>. ! It is passed by reference to the function. The first call to ! ldap_next_attribute() is made with the <parameter>result_entry_identifier</parameter> returned ! from <function>ldap_first_attribute</function>. ! <para> ! see also <function>ldap_get_attributes</function> </refsect1> </refentry> --- 808,825 ---- <paramdef>int <parameter>ber_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns the next attribute in an entry on success and false on ! error. <para> ! <function>ldap_next_attribute</function> is called to retrieve ! the attributes in an entry. The internal state of the pointer is ! maintained by the <parameter>ber_identifier</parameter>. It is ! passed by reference to the function. The first call to ! <function>ldap_next_attribute</function> is made with the ! <parameter>result_entry_identifier</parameter> returned from ! <function>ldap_first_attribute</function>. ! <para> ! see also <function>ldap_get_attributes</function> </refsect1> </refentry> *************** *** 782,799 **** <paramdef>int <parameter>link_identifier</parameter></paramdef> <paramdef>int <parameter>result_entry_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns entry identifier for the next entry in the result whose entries ! are being read starting with ldap_first_entry(). If there are no more ! entries in the result then it returns false. ! <para> ! ldap_next_entry() function is used to retrieve the entries stored in ! the result. Successive calls to the ldap_next_entry() return entries one ! by one till there are no more entries. The first call to ldap_next_entry() ! is made after the call to <function>ldap_first_entry</function> with the ! result_identifier as returned from the ldap_first_entry(). ! <para> ! see also <function>ldap_get_entries</function> </refsect1> </refentry> --- 836,856 ---- <paramdef>int <parameter>link_identifier</parameter></paramdef> <paramdef>int <parameter>result_entry_identifier</parameter></paramdef> </funcsynopsis> + <para> + Returns entry identifier for the next entry in the result whose + entries are being read starting with + <function>ldap_first_entry</function>. If there are no more + entries in the result then it returns false. + <para> + <function>ldap_next_entry</function> function is used to retrieve + the entries stored in the result. Successive calls to the + <function>ldap_next_entry</function> return entries one by one + till there are no more entries. The first call to + <function>ldap_next_entry</function> is made after the call to + <function>ldap_first_entry</function> with the result_identifier + as returned from the <function>ldap_first_entry</function>. <para> ! see also <function>ldap_get_entries</function> </refsect1> </refentry> *************** *** 810,822 **** <paramdef>int <parameter>link_identifier</parameter></paramdef> <paramdef>string <parameter>base_dn</parameter></paramdef> <paramdef>string <parameter>filter</parameter></paramdef> </funcsynopsis> <para> ! Returns a search result identifier or false on error. <para> ! ldap_read() performs the search for a specified filter on the directory ! with the scope LDAP_SCOPE_BASE. So it is equivalent to reading an entry ! from the directory. </refsect1> </refentry> --- 867,892 ---- <paramdef>int <parameter>link_identifier</parameter></paramdef> <paramdef>string <parameter>base_dn</parameter></paramdef> <paramdef>string <parameter>filter</parameter></paramdef> + <paramdef>array + <parameter><optional>attributes</optional</parameter></paramdef> </funcsynopsis> <para> ! Returns a search result identifier or false on error. <para> ! <function>ldap_read</function> performs the search for a ! specified filter on the directory with the scope ! LDAP_SCOPE_BASE. So it is equivalent to reading an entry from the ! directory. ! <para> ! An empty filter is not allowed. If you want to retrieve ! absolutely all information for this entry, use a filter of ! "objectClass=*". If you know which entry types are used on the ! directory server, you might use an appropriate filter such as ! "objectClass=inetOrgPerson". ! <para> ! This call takes an optional fourth parameter which is an array of ! the attributes required. See <function>ldap_search</function> ! notes. </refsect1> </refentry> *************** *** 833,846 **** <paramdef>int <parameter>link_identifier</parameter></paramdef> <paramdef>string <parameter>base_dn</parameter></paramdef> <paramdef>string <parameter>filter</parameter></paramdef> </funcsynopsis> <para> ! Returns a search result identifier or false on error. <para> ! ldap_search() performs the search for a specified filter on the directory ! with the scope of LDAP_SCOPE_SUBTREE. This is equivalent to searching ! the entire directory. <parameter>base_dn</parameter> specifies the base DN ! for the directory. </refsect1> </refentry> --- 903,990 ---- <paramdef>int <parameter>link_identifier</parameter></paramdef> <paramdef>string <parameter>base_dn</parameter></paramdef> <paramdef>string <parameter>filter</parameter></paramdef> + <paramdef>array + <parameter><optional>attributes</optional></parameter></paramdef> </funcsynopsis> <para> ! Returns a search result identifier or false on error. <para> ! <function>ldap_search</function> performs the search for a ! specified filter on the directory with the scope of ! LDAP_SCOPE_SUBTREE. This is equivalent to searching the entire ! directory. <parameter>base_dn</parameter> specifies the base DN ! for the directory. ! <para> ! There is a optional fourth parameter, that can be added to ! restrict the attributes and values returned by the server to just ! those required. This is much more efficient than the default ! action (which is to return all attributes and their associated ! values). The use of the fourth parameter should therefore be ! considered good practice. ! <para> ! The fourth parameter is a standard PHP string array of the ! required attributes, eg array("mail","sn","cn") Note that the ! "dn" is always returned irrespective of which attributes types ! are requested. ! <para> ! Note too that some directory server hosts will be configured to ! return no more than a preset number of entries. If this occurs, ! the server will indicate that it has only returned a partial ! results set. ! <para> ! The search filter can be simple or advanced, using boolean ! operators in the format described in the LDAP doumentation (see ! the Netscape Directory SDK for full information on filters). ! <para> ! The example below retrieves the organizational unit, surname, ! given name and email address for all people in "My Company" where ! the surname or given name contains the substring $person. This ! example uses a boolean filter to tell the server to look for ! information in more than one attribute. ! ! <example> ! <title>LDAP search</title> ! <programlisting role=php> ! // $ds is a valid link identifier for a directory server ! ! // $person is all or part of a person's name, eg "Jo" ! ! $dn = "o=My Company, c=US"; ! $filter="(|(sn=$person*)(givenname=$person*))"; ! $justthese = array( "ou", "sn", "givenname", "mail"); ! ! $sr=ldap_search($ds, $dn, $filter, $justthese); ! ! $info = ldap_get_entries($ds, $sr); ! ! print $info["count"]." entries returned&lt;p>"; ! </programlisting> ! </example> ! ! <para> ! ! When you perform a search, and too much data comes back (alot of ! entries) you will get a warning, and ! <function>ldap_get_entries</function> will fail. The trick here ! is to turn off the warnings, then check the return value. ! ! <informalexample> ! <literallayout> ! $normerr = error_reporting (); ! error_reporting (0); // turn off warnings! ! $sr = ldap_search ($ds, $dn, $searchfor); ! $normerr = error_reporting ($normerr); ! if (!$sr) { ! print "too many entries!"; ! } else ..... ! </literallayout> ! </informalexample> ! ! <para> ! You could try narrowing the scope, by adding an extra filter ! eg. (cn=a*), but It would be nicer to be able to grab the ! results in bits (eg. 1-100, 101-200...). ! </refsect1> </refentry> *************** *** 857,865 **** <paramdef>int <parameter>link_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. ! <para> ! ldap_unbind() function unbinds from the LDAP directory. </refsect1> </refentry> --- 1001,1010 ---- <paramdef>int <parameter>link_identifier</parameter></paramdef> </funcsynopsis> <para> ! Returns true on success and false on error. ! <para> ! <function>ldap_unbind</function> function unbinds from the LDAP ! directory. </refsect1> </refentry> -- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe@lists.php.net For help: php-dev-help@lists.php.net