ldap_read
(PHP 4, PHP 5, PHP 7, PHP 8)
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 のサポートが追加されました。
|
User Contributed Notes 5 notes
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.In the previous example the
$ds = ldap.myserver.com // your ldap server
should be
$ds = ldap_connect( "ldap.myserver.com" ) ; // your ldap serverThe 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
)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 timeThis 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.