diff --git a/reference/ldap/book.xml b/reference/ldap/book.xml index 64c39aa2af..0be0fb8d85 100644 --- a/reference/ldap/book.xml +++ b/reference/ldap/book.xml @@ -1,11 +1,11 @@ - + Lightweight Directory Access Protocol LDAP - + &reftitle.intro; @@ -13,9 +13,9 @@ LDAP is the Lightweight Directory Access Protocol, and is a protocol used to access "Directory Servers". The Directory is a special kind of database that holds information in a tree - structure. + structure. - + The concept is similar to your hard disk directory structure, except that in this context, the root directory is "The world" and the first level subdirectories are "countries". Lower levels @@ -34,7 +34,7 @@ The forwards slash marks each division in the reference, and the sequence is read from left to right. - + The equivalent to the fully qualified file reference in LDAP is the "distinguished name", referred to simply as "dn". An example dn might be: @@ -84,17 +84,18 @@ - + The Netscape SDK contains a helpful Programmer's Guide in HTML format. - + &reference.ldap.setup; &reference.ldap.constants; &reference.ldap.using; + &reference.ldap.controls; &reference.ldap.examples; &reference.ldap.reference; diff --git a/reference/ldap/controls.xml b/reference/ldap/controls.xml new file mode 100644 index 0000000000..2d8ef5f8a9 --- /dev/null +++ b/reference/ldap/controls.xml @@ -0,0 +1,207 @@ + + + + + LDAP controls + + Controls are special objects which may be send 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. + + + + 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 + (boolean) + + + + 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_PAGEDRESULTS + Expected keys are [size] and [cookie] + + + + + LDAP_CONTROL_ASSERT + Expected key is filter + + + + + LDAP_CONTROL_VALUESRETURNFILTER + Expected key is filter + + + + + LDAP_CONTROL_PRE_READ + Expected key is attrs + + + + + LDAP_CONTROL_POST_READ + Expected key is attrs + + + + + LDAP_CONTROL_SORTREQUEST + Expects an array of arrays with keys attr, [oid], [reverse]. + + + + + LDAP_CONTROL_VLVREQUEST + Expected keys are before, after, attrvalue|(offset, count), [context] + + + + + + + The following controls do not need any value: + + + + 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_PASSWORDPOLICYRESPONSE + Keys are expire, grace, [error] + + + + + LDAP_CONTROL_PAGEDRESULTS + Keys are size, cookie + + + + + LDAP_CONTROL_PRE_READ + Keys are dn and LDAP attributes names + + + + + LDAP_CONTROL_POST_READ + Keys are dn and LDAP attributes names + + + + + LDAP_CONTROL_SORTRESPONSE + Keys are errcode, [attribute] + + + + + LDAP_CONTROL_VLVRESPONSE + Keys are target, count, errcode, context + + + + + + + + +