[DOC-CVS] [doc-en] master: Clarify ldap_connect/ldap_bind/ldap_set_option behavior (#5275)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-19T12:27:32+02:00

Commit: https://github.com/php/doc-en/commit/87d63aa1a3fc86d64dc994332042fdd2c13bf3d8
Raw diff: https://github.com/php/doc-en/commit/87d63aa1a3fc86d64dc994332042fdd2c13bf3d8.diff

Clarify ldap_connect/ldap_bind/ldap_set_option behavior (#5275)

* Clarify ldap_connect/ldap_bind/ldap_set_option behavior

Fixes #3526

* ldap: use simpara for description paragraphs (style guide)

* ldap: use literal for LDAP_OPT_X_TLS_* wildcard

Changed paths:
  M  reference/ldap/functions/ldap-bind.xml
  M  reference/ldap/functions/ldap-connect.xml
  M  reference/ldap/functions/ldap-set-option.xml


Diff:

diff --git a/reference/ldap/functions/ldap-bind.xml b/reference/ldap/functions/ldap-bind.xml
index 8a3b9ddf4329..4f204ca3ca92 100644
--- a/reference/ldap/functions/ldap-bind.xml
+++ b/reference/ldap/functions/ldap-bind.xml
@@ -14,9 +14,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>
    Binds to the LDAP directory with specified RDN and password.
-  </para>
+  </simpara>
+  <note>
+   <simpara>
+    This function establishes the actual network connection to the
+    LDAP server (since <function>ldap_connect</function> only
+    initializes connection parameters). Any options that affect the
+    connection, such as <constant>LDAP_OPT_PROTOCOL_VERSION</constant>
+    or TLS-related options, must be set before calling this function.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/ldap/functions/ldap-connect.xml b/reference/ldap/functions/ldap-connect.xml
index d527d6803146..03db3ea857d2 100644
--- a/reference/ldap/functions/ldap-connect.xml
+++ b/reference/ldap/functions/ldap-connect.xml
@@ -22,15 +22,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>
-   Creates an <classname>LDAP\Connection</classname> connection and checks whether the given
-   <parameter>uri</parameter> is plausible.
-  </para>
+  <simpara>
+   Creates an <classname>LDAP\Connection</classname> instance and checks
+   whether the given <parameter>uri</parameter> is plausible.
+  </simpara>
+  <note>
+   <simpara>
+    This function does <emphasis>not</emphasis> open a network connection.
+    It only validates the URI syntax and initializes connection parameters.
+    The actual TCP connection is established when
+    <function>ldap_bind</function> is called.
+   </simpara>
+  </note>
   <note>
    <simpara>
-    This function does <emphasis>not</emphasis> open a connection.
-    It checks whether the given parameters are plausible and can be used
-    to open a connection as soon as one is needed.
+    Options that affect the connection setup, such as
+    <constant>LDAP_OPT_PROTOCOL_VERSION</constant> and TLS-related
+    options (<literal>LDAP_OPT_X_TLS_*</literal>), must be set
+    using <function>ldap_set_option</function> after calling this
+    function and before calling <function>ldap_bind</function>.
+    TLS-related options must be set globally (by passing &null; as
+    the first argument to <function>ldap_set_option</function>).
    </simpara>
   </note>
  </refsect1>
diff --git a/reference/ldap/functions/ldap-set-option.xml b/reference/ldap/functions/ldap-set-option.xml
index 0c1dd9bfee42..eb7aade30a9d 100644
--- a/reference/ldap/functions/ldap-set-option.xml
+++ b/reference/ldap/functions/ldap-set-option.xml
@@ -14,9 +14,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>
    Sets the value of the specified option to be <parameter>value</parameter>.
-  </para>
+  </simpara>
+  <note>
+   <simpara>
+    TLS-related options (<literal>LDAP_OPT_X_TLS_*</literal>) must be
+    set globally by passing &null; as <parameter>ldap</parameter>,
+    because the TLS context is initialized before the per-connection
+    state is available. These options must also be set before calling
+    <function>ldap_bind</function>.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">