# LDAP コントロール

コントロールは、リクエストを処理中にサーバーの振る舞いを変更するために LDAP リクエストと一緒に送られる特別なオブジェクトです。 サーバーがレスポンスと一緒に送ってくる、 追加の情報を提供するためのコントロールも存在します。 これは通常、リクエストに付けて送られたコントロールオブジェクトへの返答になります。

> 注意:

> 全てのコントロールが、全てのLDAPサーバーによってサポートされているとは限りません。 どのコントロールをサーバーがサポートしているのかを知るには、 フィルタ (objectClass=*) を付けて空の dn を読むことで、 root DSE に問い合わせる必要があります。

> 例1 ページ分けされた結果コントロールがサポートされているかをテストする

>     <?php

>     // $ds is a valid link identifier for a directory server

>     $result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
>     if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
>       die("This server does not support paged result control");
>     }

>     ?>

PHP 7.3 以降では、全てのリクエスト関数で `controls` パラメータを使って コントロールを送信することができます。関数の拡張バージョンが存在する場合、 完全なレスポンスオブジェクトを取得したい場合は、それを使うべきです。 そうすれば、ldap_parse_result() を使ってレスポンスのコントロールをパースできます。

`controls` は、送信するコントロールごとに配列を含めなければなりません。 以下のキーが含まれます:

oid (string)
  コントロールの OID。 LDAP_CONTROL_ から始まる定数を使うべきです。 LDAP の定数 を参照ください。
iscritical (bool)
  コントロールを致命的なものとしてマークする場合、 サーバーがそのコントロールをサポートしていない場合、 またはサーバーが適用に失敗した場合、リクエストは失敗します。 コントロールによっては、 RFC で常に致命的だとマークされるべきだとされていることに注意してください。 デフォルトは `false` です。
value (mixed)
  コントロールの値。詳細は以下を参照ください。

ほとんどのコントロールの値は、サーバーに BERエンコードして送られます。 あなたは値を自分で BERエンコードするか、 配列に正しいキーを渡すことでBERエンコードを行わせることができます。 配列で渡すことをサポートしているコントロールは以下のとおりです:

- `LDAP_CONTROL_PAGEDRESULTS` 期待されるキーは [size] と [cookie] です。

- `LDAP_CONTROL_ASSERT` 期待されるキーは filter です。

- `LDAP_CONTROL_VALUESRETURNFILTER` 期待されるキーは filter です。

- `LDAP_CONTROL_PRE_READ` 期待されるキーは attrs です。

- `LDAP_CONTROL_POST_READ` 期待されるキーは attrs です。

- `LDAP_CONTROL_SORTREQUEST` attr, [oid], [reverse] をキーとして持つ配列の配列を期待しています。

- `LDAP_CONTROL_VLVREQUEST` 期待されるキーは、before, after, attrvalue|(offset, count), [context] です。

次のコントロールには、値は必要ありません:

- `LDAP_CONTROL_PASSWORDPOLICYREQUEST`

- `LDAP_CONTROL_MANAGEDSAIT`

- `LDAP_CONTROL_DONTUSECOPY`

コントロール `LDAP_CONTROL_PROXY_AUTHZ` は特別です。 なぜなら値のBERエンコードが不要だからです。よって、値を直接文字列として扱うことが出来ます。

ldap_parse_result() によってコントロールがパースされる場合、 値はサポートされていれば配列に変換されます。 サポートされているのは以下です:

- `LDAP_CONTROL_PASSWORDPOLICYRESPONSE` expire, grace, [error] がキーになります。

- `LDAP_CONTROL_PAGEDRESULTS` size, cookie がキーになります

- `LDAP_CONTROL_PRE_READ` dn と LDAP の属性名がキーになります。

- `LDAP_CONTROL_POST_READ` dn と LDAP の属性名がキーになります。

- `LDAP_CONTROL_SORTRESPONSE` errcode, [attribute] がキーになります。

- `LDAP_CONTROL_VLVRESPONSE` target, count, errcode, context がキーになります。

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open