ldap_read

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_read — Lê uma entrada

Descrição

ldap_read(
    LDAP\Connection|array $ldap,
    array|string $base,
    array|string $filter,
    array $attributes = [],
    int $attributes_only = 0,
    int $sizelimit = -1,
    int $timelimit = -1,
    int $deref = LDAP_DEREF_NEVER,
    ?array $controls = null
): LDAP\Result|array|false

Realiza a pesquisa para um filtro especificado em filter no diretório com o escopo LDAP_SCOPE_BASE. É equivalente a ler uma entrada do diretório.

Também é possível realizar buscas paralelas. Neste caso, o primeiro argumento deve ser um array de instâncias de LDAP\Connection, em vez de apenas uma instância. Se as pesquisas não devem usar a mesma DN base e filtro, um array de DNs base e/ou um array de filtros podem ser passados como argumentos. Esses arrays devem ter o mesmo tamanho que o array de instâncias de LDAP\Connection, já que as primeiras entradas dos arrays são usadas para uma pesquisa, as segundas entradas são usadas para outra e assim por diante. Ao fazer pesquisas paralelas, um array de instâncias de LDAP\Result é retornado, exceto em caso de erro, quando o valor retornado será false.

Parâmetros

ldap

Uma instância de LDAP\Connection, retornada por ldap_connect().

base

O DN base para o diretório.

filter

Um filtro vazio não é permitido. Se for desejado recuperar absolutamente todas as informações para esta entrada, deve ser usado um filtro de objectClass=*. Se são conhecidos os tipos de entrada usados no servidor de diretório, pode-se usar um filtro apropriado tal como objectClass=inetOrgPerson.

attributes

Um array dos atributos requeridos, ex.: array("mail", "sn", "cn"). Observe que o "dn" é sempre retornado independente de que tipos de atributos são requisitados.

Usar este parâmetro é muito mais eficiente que a ação padrão (que é retornar todos os atributos e seus valores associados). O uso deste parâmetro deve portanto ser considerado uma boa prática.

attributes_only

Deve ser definido apra 1 se apenas tipos de atributos são pretendidos. Se definido para 0, tanto os tipos quanto os valores dos atributos são buscados, que é o comportamento padrão.

sizelimit

Habilita o limite de entradas buscadas. Definir para 0 é o mesmo que não definir limite.

Nota:
Este parâmetro NÃO consegue substituir o limite de tamanho definido no servidor. Ainda assim, ele pode ser definido para um valor menor.

Alguns servidores de diretório estarão configurados para retornar um número limutado de entradas. Se isto ocorrer, o servidor indicará que retornou um conjunto parcial de resultados. Isto também ocorre se este parâmetro for usado para limitar a contagem de entradas buscadas.

timelimit

Define o número de segundos gastos na busca. Definir para 0 é o mesmo que não definir limite.

Nota:
Este parâmetro NÃO consegue substituir o limite de tempo definido no servidor. Ainda assim, valores menores podem ser definidos.

deref

Especifica como os apelidos são gerenciados durante a busca. Pode ser uma das constantes a seguir:

LDAP_DEREF_NEVER - (padrão) apelidos nunca são desreferenciados.
LDAP_DEREF_SEARCHING - apelidos devem ser desreferenciados durante a busca mas não ao localizar o objeto base da busca.
LDAP_DEREF_FINDING - apelidos devem ser desreferenciados ao localizar o objeto base mas não durante a pesquisa.
LDAP_DEREF_ALWAYS - apelidos devem ser desreferenciados sempre.

controls

Array de Controles LDAP que serão enviados com a requisição.

Valor Retornado

Retorna uma instância de LDAP\Result, um array de instâncias de LDAP\Result, ou false em caso de falha.

Registro de Alterações

Versão	Descrição
8.1.0	O parâmetro `ldap` agora espera uma instância de LDAP\Connection; anteriormente, um resource `ldap link` válido era esperado.
8.1.0	Agora retorna uma instância de LDAP\Result; anteriormente, um resource era retornado.
8.0.0	O parâmetro `controls` agora pode ser nulo; anteriormente, o padrão era `[]`.
4.0.5	Adicionado suporte a pesquisas paralelas. Consulte ldap_search() para detalhes.
7.3.0	Adicionado suporte para `controls`.

Improve This Page

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 6 notes

down

cnicholl at yahoo dot com ¶

18 years ago

Clarification of the ldap_read command syntax:  

If you just want to pull certain attributes from an object and you already know it's dn, the ldap_read command can do this as illustrated below.  It will be less overhead than ldap_search.

The string base_dn which is normally used to set the top context for a recursive ldap_search is used slightly differently with this command.  It is used to specify the actual object with the full dn.  (Hopefully this saves someone else a couple hours trying this command out.)

<?php
$ds = ldap.myserver.com // your ldap server
  $dn = "cn=username,o=My Company, c=US"; //the object itself instead of the top search level as in ldap_search
  $filter="(objectclass=*)"; // this command requires some filter
  $justthese = array("ou", "sn", "givenname", "mail"); //the attributes to pull, which is much more efficient than pulling all attributes if you don't do this
      $sr=ldap_read($ds, $dn, $filter, $justthese);
          $entry = ldap_get_entries($ds, $sr);

echo $entry[0]["mail"][0] . "is the email address of the cn your requested";
echo $entry[0]["sn"][0] . "is the sn of the cn your requested";
ldap_close($ds);
?> 

This prints out the specified users mail and surname for example.

down

ronny at nxc dot no ¶

11 years ago

The array in the attributes parameter needs to be an indexed array with numeric keys in ascending order. Like this:

Array
(
    [0] => this
    [1] => is
    [2] => a
    [3] => test
)

If there are missing keys in the array, then no result will be returned. This will not work:

Array
(
    [0] => this
    [1] => is
    [3] => test
)

down

me at example dot com ¶

16 years ago

In the previous example the

$ds = ldap.myserver.com // your ldap server

should be 

$ds = ldap_connect( "ldap.myserver.com" ) ; // your ldap server

down

ehalls at gmail dot com ¶

6 years ago

For those debugging a wrapper, akin to symfony's client wrapper for these functions and since there is crap documentation on a full cycle of pulling a single record vs multiple, etc.

For this one:
YOU MUST call ldap_get_entries after this function call. 

AND PLEASE if you implement a wrapper, prime it with the initial entry else it makes no sense to execute without returning something easily visible as successful.

WHEN query->execute() and you get a collection.. make sure the entry field in the collection has at least the first entry primed.. wasted so much time because it was looking empty. 

AND this entire adapter needs to be wrapped with a less retarded usage pattern via an STL lib wrapper, mysticism( bad design) begone.
123.. not 4290234~"wds

Thanks for your time

down

sbarnum at mac dot com ¶

22 years ago

This differs from ldap_search() by not recursing down to sub-entries.  if you know the dn of the item you're looking for and only want info on that entry, use ldap_read() and pass it the full dn of the item you want.



It also seems that you'd alway want something like objectclass=* for the filter, since you're only searching on one entry.

down

-22

guillaumeinnov24 at gmail dot com ¶

9 years ago

Unfortunately, userPasswords seem to be NOT retrievable with ldap_read();

＋add a note