ldap_read

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

ldap_read — エントリを読み込む

説明

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

指定したフィルタ filter を使用し、スコープ LDAP_SCOPE_BASE でディレクトリを検索します。これは、ディレクトリからエントリを読み込むことと同じ意味です。

並列検索も可能です。並列検索を行うには、単一の LDAP\Connection のインスタンスではなく、それの配列を使用します。同じベース DN を使用したくない場合や全ての検索について同じフィルタを使用したくない場合、ベース DN の配列またはフィルタの配列を使用することが可能です。これらの配列は、LDAP\Connection の配列と同じ大きさである必要があります。これは、その配列の最初が一回の検索で使用され、2 番目のエントリが他の検索で使用されるといったようになるからです。並列検索を実行する際、エラーの場合を除き、LDAP\Result の配列が返されます。エラーの場合は、返される値は false になります。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

base

ディレクトリのベース DN。

filter

空のフィルタは指定できません。このエントリに関する全ての情報を完全に取得したい場合は、 objectClass=* というフィルタを使用してください。ディレクトリサーバーで使用されるエントリの型が分かっている場合、 objectClass=inetOrgPerson のように適切なフィルタを使用することができます。

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:
このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、事前に設定された数以上のエントリを返さないようになっているものもあります。この場合、サーバーでは、それが結果セットのすべてではないことを通知します。このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。これを 0 にすると無制限であることを表します。

注意:
このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。以下のいずれかとなります。

LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
LDAP_DEREF_ALWAYS - エイリアスを常に参照します。 always.

controls

リクエストと一緒に送信する LDAP コントロールの配列

戻り値

LDAP\Result のインスタンスか、LDAP\Result のインスタンスの配列を返します。失敗した場合に false を返します

変更履歴

バージョン	説明
8.1.0	引数 `ldap` は、LDAP\Connection クラスのインスタンスを期待するようになりました。これより前のバージョンでは、有効な `ldap link` リソースを期待していました。
8.1.0	LDAP\Result クラスのインスタンスを返すようになりました。これより前のバージョンでは、リソースを返していました。
8.0.0	`controls` は、nullable になりました。これより前のバージョンでは、デフォルト値が `[]` でした。
7.3.0	`controls` のサポートが追加されました。

Found A Problem?

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

＋add a note

User Contributed Notes 5 notes

down

cnicholl at yahoo dot com ¶

19 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

me at example dot com ¶

17 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

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

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

-1

sbarnum at mac dot com ¶

23 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.

＋add a note