Search Functions - Page 11

The power of LDAP comes from the versatility of search operations that can be performed on the directory. Several functions are provided by PHP not just to search but also to manipulate and process results.

ldap_search()

int ldap_search(int link_identifier, string base_dn, string filter
                [, array attributes [, int attrsonly [, int sizelimit
                [, int timelimit [, int deref]]]]])

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 subtree under the specified base DN that is specified by base_dn. The search filter can be simple or advanced, using Boolean operators in the format described in the LDAP documentation. It returns a search result identifier or false on error.

There is an optional fourth parameter attributes 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. The fourth parameter is a standard PHP string array of the required attributes, for example array (mail, sn, cn). Note that the dn is always returned irrespective of which attributes types are requested.

The fifth parameter, attrsonly, specifies if only attributes need to be returned. Setting this to 1 returns only attributes, whereas setting this to 0 returns attributes and values.

It is possible to limit the number of entries returned as result of the search using the sizelimit attribute. Some directory servers will be configured to return no more than a preset number of entries. This parameter is therefore limited by the corresponding server-side maximum for the number of entries to be returned.

The timelimit attribute determines the amount of time in seconds to spend on a search operation. Setting this argument to 0 is equivalent to unlimited time. However, similar to the sizelimit argument, the maximum time is limited by the maximum time the server has been configured to spend on a search query.

The last argument, deref, determines the behavior in terms of dealing with aliases during the search. This argument can take the following values:

• LDAP_DEREF_NEVER Aliases are never dereferenced in this case. This is the default case.
• LDAP_DEREF_ALWAYS Aliases should always be dereferenced.
• LDAP_DEREF_SEARCHING — Aliases should be dereferenced during the search but not when locating the base object of the search.
• LDAP_DEREF_FINDING Aliases should be dereferenced when locating the base object but not during the search.

ldap_compare()

int ldap_compare(int link_identifier, string dn,
                  string attribute, string value)

ldap_compare() is used to compare the value of a string with an attribute of an entry in the directory specified by a DN. It takes a link identifier as the first parameter followed by the DN of the entry whose attribute is to be compared against, followed by the attribute itself and finally the string itself. It returns true if the attribute value matches the string exactly, false if not, and -1 if the comparison operation failed. However, this function cannot be used to compare binary values and is available only from PHP 4.0.2 and upwards:

<?php
if (!($conn=ldap_connect("ldapmachine.myorg.com"))) {
    echo("Failed to connect to the server");
} else {
    if (ldap_bind($conn)) {
        $toCompare = "richard";
        $dn = "mail=richardc@xyz.com, o=myorg, c=us";
        $attr = "cn";

        if(($ret = ldap_compare($conn, $dn, $attr, $toCompare)) < 0) {
            echo("ldap_compare failed");
        } elseif ($ret == TRUE) {
            echo("Comparison succeeded");
        } elseif ($ret == FALSE) {
            echo("Comparison failed");
        }
    } else {
        echo("Failed to bind to the server");
            ldap_close($conn);
    }
}
?>

ldap_read()

int ldap_read(int link_identifier, string base_dn, string filter
              [, array attributes [, int attrsonly [, int sizelimit
              [, int timelimit [, int deref]]]]])

ldap_read() performs the search for a specified filter on the directory with the scope LDAP_SCOPE_BASE, which is equivalent to reading an entry from the directory. 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.

This call takes an optional fourth parameter, which is an array of the attributes required. It returns a search result identifier, or false on error. The newly introduced parameters attrsonly, sizelimit, timelimit, and deref have exactly the same functionality as they have in the ldap_search() function.

ldap_dn2ufn() string ldap_dn2ufn(string dn) ldap_dn2ufn() function is used to turn a DN into a more user-friendly form, stripping off type names of the attributes. For example the DN 'cn=Resident Geek, o=caffeinated, c=uk' would be turned into 'Resident Geek, caffeinated, uk'.

ldap_explode_dn()

array ldap_explode_dn(string dn, int with_attrib)

ldap_explode_dn() splits a DN returned by ldap_get_dn() into its component parts, that is the RDNs. ldap_explode_dn() returns an array of all those components. with_attrib is used to request that the RDNs are returned with only values or their attributes as well. To get RDNs with attributes (attribute=value format), set with_attrib to 0, and to get only values set it to 1.

ldap_first_attribute()

string ldap_first_attribute(int link_identifier,
                            int result_entry_identifier,
                            int &ber_identifier);

ldap_first_attribute() returns the first attribute in the entry pointed by the entry identifier. Remaining attributes are retrieved by calling ldap_next_attribute() successively.

ber_identifier is an identifier to internal memory location pointer where all the results of this query are stored. It is passed by reference - the & indicates this. The same ber_identifier is passed to the ldap_next_attribute() function, which reads the next entry and then updates the pointer to the next entry.

The PHP LDAP API - Page 10
Professional PHP4 Programming
Search Functions (Cont.) - Page 12