From 882a3780a7dcdd81f8e537dc8b62c2c677c54562 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Mon, 31 Aug 2026 13:40:54 +0200
Subject: [PATCH] ldap: clarify the connect, bind and set_option behavior

---
 reference/ldap/functions/ldap-bind.xml       | 15 ++++++++---
 reference/ldap/functions/ldap-connect.xml    | 28 ++++++++++++++------
 reference/ldap/functions/ldap-set-option.xml | 15 ++++++++---
 3 files changed, 44 insertions(+), 14 deletions(-)

diff --git a/reference/ldap/functions/ldap-bind.xml b/reference/ldap/functions/ldap-bind.xml
index 5edf63b99a..b495512e33 100644
--- a/reference/ldap/functions/ldap-bind.xml
+++ b/reference/ldap/functions/ldap-bind.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: sergey Status: ready -->
+<!-- EN-Revision: 87d63aa1a3fc86d64dc994332042fdd2c13bf3d8 Maintainer: sergey Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.ldap-bind" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -15,9 +15,18 @@
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>dn</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><modifier role="attribute">#[\SensitiveParameter]</modifier><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Функция связывает LDAP-каталог с указанным RDN-именем и паролем.
-  </para>
+  </simpara>
+  <note>
+   <simpara>
+    Эта функция устанавливает фактическое сетевое соединение с LDAP-сервером,
+    поскольку функция <function>ldap_connect</function> только инициализирует
+    параметры соединения. Каждую опцию, которая влияет на соединение, например
+    <constant>LDAP_OPT_PROTOCOL_VERSION</constant> или опции, связанные с TLS,
+    требуется установить до вызова этой функции.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/ldap/functions/ldap-connect.xml b/reference/ldap/functions/ldap-connect.xml
index b4a2232036..37577f639e 100644
--- a/reference/ldap/functions/ldap-connect.xml
+++ b/reference/ldap/functions/ldap-connect.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: ca23605a1c0e46b9ec85975c6387528c32a7087f Maintainer: rjhdby Status: ready -->
+<!-- EN-Revision: 87d63aa1a3fc86d64dc994332042fdd2c13bf3d8 Maintainer: rjhdby Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.ldap-connect" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -23,15 +23,27 @@
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>host</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>389</initializer></methodparam>
   </methodsynopsis>
-  <para>
-   Создаёт объект <classname>LDAP\Connection</classname> и проверяет правдоподобность
-   заданного в параметре <parameter>uri</parameter> значения.
-  </para>
+  <simpara>
+   Создаёт объект класса <classname>LDAP\Connection</classname> и проверяет
+   правдоподобность заданного в параметре <parameter>uri</parameter> значения.
+  </simpara>
+  <note>
+   <simpara>
+    Эта функция <emphasis>не</emphasis> открывает сетевое соединение.
+    Она только проверяет синтаксис URI и инициализирует параметры соединения.
+    Фактическое TCP-соединение устанавливается при вызове функции
+    <function>ldap_bind</function>.
+   </simpara>
+  </note>
   <note>
    <simpara>
-    Эта функция <emphasis>не</emphasis> открывает соединение.
-    Она проверяет, правдоподобны ли заданные параметры и можно
-    ли, указав их, установить соединение, когда оно необходимо.
+    Опции, которые влияют на установку соединения, например
+    <constant>LDAP_OPT_PROTOCOL_VERSION</constant> и опции, связанные с TLS
+    (<literal>LDAP_OPT_X_TLS_*</literal>), требуется установить функцией
+    <function>ldap_set_option</function> после вызова этой функции и до вызова
+    функции <function>ldap_bind</function>. Опции, связанные с TLS,
+    устанавливают глобально — первым аргументом функции
+    <function>ldap_set_option</function> передают значение &null;.
    </simpara>
   </note>
  </refsect1>
diff --git a/reference/ldap/functions/ldap-set-option.xml b/reference/ldap/functions/ldap-set-option.xml
index 35a53a552f..b315a5b1e9 100644
--- a/reference/ldap/functions/ldap-set-option.xml
+++ b/reference/ldap/functions/ldap-set-option.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 5b3a84935252a553528cb81b3dacb88647b57c7b Maintainer: mch Status: ready -->
+<!-- EN-Revision: 87d63aa1a3fc86d64dc994332042fdd2c13bf3d8 Maintainer: mch Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.ldap-set-option" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -15,9 +15,18 @@
    <methodparam><type>int</type><parameter>option</parameter></methodparam>
    <methodparam><type class="union"><type>array</type><type>string</type><type>int</type><type>bool</type></type><parameter>value</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Функция устанавливает для опции значение <parameter>value</parameter>.
-  </para>
+  </simpara>
+  <note>
+   <simpara>
+    Опции, связанные с TLS (<literal>LDAP_OPT_X_TLS_*</literal>), устанавливают
+    глобально — в параметре <parameter>ldap</parameter> передают значение &null;,
+    поскольку контекст TLS инициализируется до того, как становится доступно
+    состояние конкретного соединения. Эти опции требуется установить также
+    до вызова функции <function>ldap_bind</function>.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">