ldap_search

Descripción

resource ldap_search ( resource identificador_de_conexion, string dn_base, string filtro [, array atributos [, int solo_atributos [, int tamano_limite [, int tiempo_limite [, int deref]]]]] )

Devuelve un identificador de resultado de búsqueda o FALSE en caso de error.

ldap_search() realiza la búsqueda según el filtro especificado con alcance LDAP_SCOPE_SUBTREE. Esto es equivalente a buscar en el directorio entero. dn_base especifica el DN base para el directorio.

Existe un cuarto parámetro opcional que puede ser añadido para restringir los atributos y valores devueltos por el servidor a sólo los requeridos. Es mucho más eficiente que la acción por defecto (que devolverá todos los atributos y sus valores asociados). El uso del cuarto parámetro debe ser por tanto considerado una práctica recomendable.

El cuerto parámetro es un array estándar de PHP con los atributos requeridos, por ejemplo array("mail","sn","cn"). Nota: "dn" siempre es devuelto independientemente de que tipos de atributos sean solicitados.

También hay que tener en cuenta que algunos servidores de directorio están configurados para devolver un cierto número de entradas como máximo. Si esto ocurre, el servidor indicará que solo devuelve un conjunto parcial de los resultados. Esto también se produce si el sexto parámetro tamano_limite se emplea para limitar el número de entradas devueltas.

El quinto parámetro solo_atributos se puede poner a 1 si solo se quieren obtener los tipos de los atributos. Si se le da un valor de 0, se obtienen los tipos de los atributos y sus valores, que es el comportamiento por defecto.

El sexto parámetro tamano_limite permite limitar el número de entradas devueltas. Si se le da un valor de 0, no se establece ningún límite. NOTA: Este parámetro no prevalece sobre los límites establecidos por el servidor, aunque si que permite establecerlo a un valor inferior.

El séptimo parámetro tiempo_limite establece el número de segundos que se dedica a realizar la búsqueda. Si se le da un valor de 0, no se establece ningún límite. NOTA: Este parámetro no prevalece sobre los límites establecidos por el servidor, aunque si que permite establecerlo a un valor inferior.

El octavo parámetro deref especifica como se tratan los alias durante la búsqueda. Su valor debe ser uno de los siguientes:

• LDAP_DEREF_NEVER - (valor por defecto) los alias nunca se dereferencian.

• LDAP_DEREF_SEARCHING - los alias se deben dereferenciar durante las búsquedas pero no cuando se busca el objeto base de la búsqueda.

• LDAP_DEREF_FINDING - los alias se deben dereferenciar cuando se busca el objeto base de la búsqueda pero no durante la búsqueda.

• LDAP_DEREF_ALWAYS - los alias se deben dereferenciar siempre.

El filtro de búsqueda puede ser simple o avanzado, para lo que se utilizan operadores booleanos con el formato descrito en la documentación de LDAP (acceda a Netscape Directory SDK para obtener la información completa sobre los filtros).

El siguiente ejemplo recupera la unidad organizativa (ou), apellidos nombre común y dirección de email para todas las personas de "Mi Compañía", donde los apellidos o el nombre común contienen la subcadena $persona. Este ejemplo usa un filtro booleano para indicar al servidor que busque la información en más de un atributo.

Ejemplo 1. Búsqueda LDAP <?php // $ds es un identificador de conexion valido // $persona es todo o parte del nombre de una persona, por ejemplo "Pe" $dn = "o=Mi Compania, c=ES"; $filtro="(|(sn=$persona*)(givenname=$persona*))"; $solonecesito = array( "ou", "sn", "givenname", "mail"); $sr=ldap_search($ds, $dn, $filtro, $solonecesito); $info = ldap_get_entries($ds, $sr); echo $info["count"]." entradas devueltas\n"; ?>

A partir de la versión de PHP 4.0.5 es posible realizar búsquedas en paralelo. Para ello, se debe usar un array de identificadores de conexiones en lugar del habitual identificador de conexión simple. Si no se van a emplear los mismos DN base y los mismos filtros para todas las búsquedas, es posible indicar arrays para los DN base y los filtros. Estos arrays deben tener el mismo tamaño que el empleado para indicar el array de identificadores de conexiones. Al hacer búsquedas paralelas, se devuelve un array de resultados de búsqueda, excepto si se produce un error, en cuyo caso el valor devuelto es FALSE. Este comportamiento es muy parecido al habitual, salvo que antes siempre se devolvía un identificador de resultado cuando se hacía una búsqueda. Por tanto, pueden darse casos extraños en los que una búsqueda normal devuelva FALSE y la búsqueda paralela devuelva un identificador.