Управляющие объекты — специальные объекты, которые, если нужно, передают вместе с 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
должен содержать массив, который содержит массив
со следующими ключами для каждого управляющего объекта, который будет отправлен:
false
.
Бо́льшая часть значений управляющих объектов отсылается на сервер закодированными по правилам 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_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