LDAP controls
Controls are special objects which may be sent alongside an LDAP request to alter LDAP server behavior while performing the request. There may also be controls sent by the server alongside the response to provide more information, usually to answer a control object from the request.
Note:
Not all controls are supported by all LDAP servers. To know which controls are supported by a server, you need to query the root DSE by reading an empty dn with the filter (objectClass=*).
Example #1 Testing support for paged result control
<?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");
}
?>
As of PHP 7.3, you can send controls with your request in all request functions using the serverctrls parameter. When a ext version of a function exists, you should use it if you want to get access to the full response object and be able to parse response controls from it using ldap_parse_result().
serverctrls must be an array containing an array for each control to send, containing the following keys:
- oid (string)
- The OID of the control. You should use constants starting with LDAP_CONTROL_ for this. See LDAP Constants.
- iscritical (bool)
-
If a control is noted as critical, the request will fail if the
control is not supported by the server, or if it fails to be
applied. Note that some controls should always be marked as critical
as noted in the RFC introducing them. Defaults to
false. - value (mixed)
- If applicable, the value of the control. Read below for more information.
Most control values are sent to the server BER-encoded. You may either BER-encode the value yourself, or you can instead pass an array with the correct keys so that the encoding is done for you. Supported controls to be passed as an array are:
-
LDAP_CONTROL_PAGEDRESULTSExpected keys are [size] and [cookie] -
LDAP_CONTROL_ASSERTExpected key is filter -
LDAP_CONTROL_VALUESRETURNFILTERExpected key is filter -
LDAP_CONTROL_PRE_READExpected key is attrs -
LDAP_CONTROL_POST_READExpected key is attrs -
LDAP_CONTROL_SORTREQUESTExpects an array of arrays with keys attr, [oid], [reverse]. -
LDAP_CONTROL_VLVREQUESTExpected keys are before, after, attrvalue|(offset, count), [context]
The following controls do not need any value:
-
LDAP_CONTROL_PASSWORDPOLICYREQUEST -
LDAP_CONTROL_MANAGEDSAIT -
LDAP_CONTROL_DONTUSECOPY
The control LDAP_CONTROL_PROXY_AUTHZ is a special case
as its value is not expected to be BER-encoded, so you can directly
use a string for its value.
When controls are parsed by ldap_parse_result(), values are turned into an array if supported. This is supported for:
-
LDAP_CONTROL_PASSWORDPOLICYRESPONSEKeys are expire, grace, [error] -
LDAP_CONTROL_PAGEDRESULTSKeys are size, cookie -
LDAP_CONTROL_PRE_READKeys are dn and LDAP attributes names -
LDAP_CONTROL_POST_READKeys are dn and LDAP attributes names -
LDAP_CONTROL_SORTRESPONSEKeys are errcode, [attribute] -
LDAP_CONTROL_VLVRESPONSEKeys are target, count, errcode, context
