[doc-en] master: Document how to debug connection issues (#3317)

Author: Kirill Roskolii (RoSk0) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-25T17:09:28+02:00 Commit: https://github.com/php/doc-en/commit/9ade3ccfc8f1fa82f116a2b2c1e5e3f516fb11e7 Raw diff: https://github.com/php/doc-en/commit/9ade3ccfc8f1fa82f116a2b2c1e5e3f516fb11e7.diff Document how to debug connection issues (#3317) * Document how to debug connection issues * ldap: document the LDAP_OPT_DEBUG_LEVEL levels and fix the debugging example The example had a TODO, used undefined variables and said the option is ignored when set after ldap_connect(). ldap_connect() does not connect yet: set later, the option still traces the operations that follow, and set before it also traces the initialization. List the OpenLDAP levels in the constant description (PHP has no constants for them) and say that the traces go to stderr. * ldap: do not list the OpenLDAP debug levels The levels are defined by OpenLDAP, not by PHP, which has no constants for them. Say where they come from instead of copying the table. --------- Co-authored-by: lacatoire <la.catoire@gmail.com> Changed paths: M reference/ldap/constants.xml M reference/ldap/functions/ldap-set-option.xml Diff: diff --git a/reference/ldap/constants.xml b/reference/ldap/constants.xml index 31a0cc52e660..525c808093b6 100644 --- a/reference/ldap/constants.xml +++ b/reference/ldap/constants.xml @@ -226,7 +226,10 @@ </term> <listitem> <simpara> - Specifies a bitwise level for debug traces. + Specifies a bitwise level for debug traces. The traces are written to + <literal>stderr</literal>. The levels are defined by OpenLDAP, in its + <filename>ldap_log.h</filename> header; PHP does not expose them as + constants. </simpara> </listitem> </varlistentry> diff --git a/reference/ldap/functions/ldap-set-option.xml b/reference/ldap/functions/ldap-set-option.xml index 26157bbd2666..3a687f2a07cb 100644 --- a/reference/ldap/functions/ldap-set-option.xml +++ b/reference/ldap/functions/ldap-set-option.xml @@ -307,6 +307,24 @@ if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, $ctrl2))) { echo "Failed to set server controls"; } ?> +]]> + </programlisting> + </example> + <example> + <title>Debugging a connection issue</title> + <programlisting role="php"> +<![CDATA[ +<?php +// A NULL connection sets the option for the whole process (OpenLDAP only). +// Set before ldap_connect(), it also traces the initialization; set later, +// only the operations that follow are traced. +// 7 combines the OpenLDAP levels 1 (trace), 2 (packets) and 4 (arguments). +// The traces are written to stderr, not to the output of the script. +ldap_set_option(null, LDAP_OPT_DEBUG_LEVEL, 7); + +$ds = ldap_connect("ldaps://ldap.example.com:636"); +ldap_bind($ds); +?> ]]> </programlisting> </example>