# Управляющие объекты протокола LDAP

Управляющие объекты — специальные объекты, которые, если нужно, передают вместе с LDAP-запросом, чтобы изменить поведение LDAP-сервера на время исполнения запроса. Вместе с ответом сервер может также отправлять управляющие объекты, обычно чтобы сообщить дополнительную информацию в ответ на управляющий объект из запроса.

> Замечание:

> Не каждый LDAP-сервер поддерживает все управляющие объекты. Чтобы определить, какие управляющие объекты поддерживает сервер, запрашивают корневую запись DSE путём чтения пустого dn-имени с фильтром (objectClass=*).

> Пример #1 Тестирование поддержки управления пагинацией результата

>     <?php

>     // $ds — допустимый идентификатор соединения с сервером каталогов

>     $result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
>     if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
>       die("Этот сервер не поддерживает управление пагинацией");
>     }

>     ?>

Начиная с PHP 7.3 управляющие объекты отправляют в запросе через параметр `controls` функций запроса. Разработчик должен работать с расширенной версией функции, если ext-вариант функции существует, если нужно получить доступ к полному объекту ответа и разбору функцией ldap_parse_result() управляющих объектов из объекта ответа.

Параметр `controls` должен содержать массив, который содержит массив со следующими ключами для каждого управляющего объекта, который будет отправлен:

oid (string)
  OID-идентификатор управляющего объекта. Параметр принимает константы, имена которых начинаются на LDAP_CONTROL_. Смотрите раздел «Константы LDAP».
iscritical (bool)
  Запрос завершится ошибкой, если управляющий объект пометили как критичный, а сервер не поддерживает такой управляющий объект, либо если объект невозможно применить. Обратите внимание, что отдельные объекты требуется помечать критичными в кажом запросе, как отмечает стандарт RFC, который представляет управляющий объект. Значение по умолчанию — `false`.
value (mixed)
  Значение управляющего объекта, если нужно. Подробнее о доступных значениях описание расскажет в абзаце, который идёт ниже.

Бо́льшая часть значений управляющих объектов отсылается на сервер закодированными по правилам BER. Разработчики BER-кодируют значения сами или вместо этого передают массив с корректными ключами, и тогда значения закодирует PHP. Поддерживаемые управляющие объекты:

- `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