From 42217c6c1feee770a5592c05421e7718a593649c Mon Sep 17 00:00:00 2001
From: Gina Peter Banyard <girgias@php.net>
Date: Thu, 14 Nov 2024 02:32:54 +0000
Subject: [PATCH] PHP-8.4: LDAP changes

---
 reference/ldap/functions/ldap-exop-sync.xml | 144 +++++++++++---------
 reference/ldap/functions/ldap-exop.xml      |  85 +++++++-----
 2 files changed, 126 insertions(+), 103 deletions(-)

diff --git a/reference/ldap/functions/ldap-exop-sync.xml b/reference/ldap/functions/ldap-exop-sync.xml
index 9c4bef742dc7..c626706471d6 100644
--- a/reference/ldap/functions/ldap-exop-sync.xml
+++ b/reference/ldap/functions/ldap-exop-sync.xml
@@ -16,84 +16,96 @@
    <methodparam choice="opt"><type>string</type><parameter role="reference">response_data</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter role="reference">response_oid</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
-
-  </para>
-
-  &warn.undocumented.func;
-
+  <simpara>
+   Performs an extended operation on the specified <parameter>ldap</parameter> with
+   <parameter>request_oid</parameter> the OID of the operation and
+   <parameter>request_data</parameter> the data.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>ldap</parameter></term>
-     <listitem>
-      <para>
-       &ldap.parameter.ldap;
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>request_oid</parameter></term>
-     <listitem>
-      <para>
-
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>request_data</parameter></term>
-     <listitem>
-      <para>
-
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>controls</parameter></term>
-     <listitem>
-      <para>
-
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>response_data</parameter></term>
-     <listitem>
-      <para>
-
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>response_oid</parameter></term>
-     <listitem>
-      <para>
-
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>ldap</parameter></term>
+    <listitem>
+     <para>
+      &ldap.parameter.ldap;
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>request_oid</parameter></term>
+    <listitem>
+     <para>
+      The extended operation request OID.
+      Can be one of the
+      <constant>LDAP_EXOP_<replaceable>*</replaceable></constant>
+      constants,
+      or a string with the OID of the operation.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>request_data</parameter></term>
+    <listitem>
+     <para>
+      The extended operation request data.
+      May be NULL for some operations like <constant>LDAP_EXOP_WHO_AM_I</constant>,
+      may also need to be BER encoded.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>controls</parameter></term>
+    <listitem>
+     <para>
+      Array of <link linkend="ldap.controls">LDAP Controls</link> to send with the request.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>response_data</parameter></term>
+    <listitem>
+     <para>
+      Will be filled with the extended operation response data if provided.
+      If not provided <function>ldap_parse_exop</function> may be used on the
+      result object later to get this data.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>response_oid</parameter></term>
+    <listitem>
+     <para>
+      Will be filled with the response OID if provided,
+      usually equal to the request OID.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-
-  </para>
+  <simpara>
+   When used with <parameter>response_data</parameter>,
+   returns &true; on success or &false; on error.
+   When used without <parameter>response_data</parameter>,
+   returns a result identifier or &false; on error.
+  </simpara>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>ldap_exop</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>ldap_exop</function></member>
+   <member><function>ldap_exop_whoami</function></member>
+   <member><function>ldap_exop_refresh</function></member>
+   <member><function>ldap_exop_passwd</function></member>
+   <member><function>ldap_parse_result</function></member>
+   <member><function>ldap_parse_exop</function></member>
+  </simplelist>
  </refsect1>
 
 </refentry>
diff --git a/reference/ldap/functions/ldap-exop.xml b/reference/ldap/functions/ldap-exop.xml
index 720febcaa0cc..3d73f69005c9 100644
--- a/reference/ldap/functions/ldap-exop.xml
+++ b/reference/ldap/functions/ldap-exop.xml
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
 <refentry xml:id="function.ldap-exop" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ldap_exop</refname>
@@ -23,6 +22,12 @@
    <parameter>request_oid</parameter> the OID of the operation and
    <parameter>request_data</parameter> the data.
   </para>
+  <warning>
+   <simpara>
+    Using more than 4 parameters has been deprecated,
+    use <function>ldap_exop_sync</function> instead.
+   </simpara>
+  </warning>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -40,7 +45,11 @@
     <term><parameter>request_oid</parameter></term>
     <listitem>
      <para>
-       The extended operation request OID. You may use one of <constant>LDAP_EXOP_START_TLS</constant>, <constant>LDAP_EXOP_MODIFY_PASSWD</constant>, <constant>LDAP_EXOP_REFRESH</constant>, <constant>LDAP_EXOP_WHO_AM_I</constant>, <constant>LDAP_EXOP_TURN</constant>, or a string with the OID of the operation you want to send.
+      The extended operation request OID.
+      Can be one of the
+      <constant>LDAP_EXOP_<replaceable>*</replaceable></constant>
+      constants,
+      or a string with the OID of the operation.
      </para>
     </listitem>
    </varlistentry>
@@ -64,9 +73,9 @@
     <term><parameter>response_data</parameter></term>
     <listitem>
      <para>
-       Will be filled with the extended operation response data if provided.
-       If not provided you may use ldap_parse_exop on the result object
-       later to get this data.
+      Will be filled with the extended operation response data if provided.
+      If not provided <function>ldap_parse_exop</function> may be used on the
+      result object later to get this data.
      </para>
     </listitem>
    </varlistentry>
@@ -91,27 +100,32 @@
 
  <refsect1 role="changelog">
   &reftitle.changelog;
-  <para>
-   <informaltable>
-    <tgroup cols="2">
-     <thead>
-      <row>
-       <entry>&Version;</entry>
-       <entry>&Description;</entry>
-      </row>
-     </thead>
-     <tbody>
-      &ldap.changelog.ldap-object;
-      <row>
-       <entry>7.3.0</entry>
-       <entry>
-        Support for <parameter>controls</parameter> added
-       </entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </informaltable>
-  </para>
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       Using more than 4 parameters has been deprecated,
+       use <function>ldap_exop_sync</function> instead.
+      </entry>
+     </row>
+     &ldap.changelog.ldap-object;
+     <row>
+      <entry>7.3.0</entry>
+      <entry>
+       Support for <parameter>controls</parameter> added
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
  </refsect1>
 
  <refsect1 role="examples">
@@ -159,20 +173,17 @@ if ($ds) {
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>ldap_parse_result</function></member>
-    <member><function>ldap_parse_exop</function></member>
-    <member><function>ldap_exop_whoami</function></member>
-    <member><function>ldap_exop_refresh</function></member>
-    <member><function>ldap_exop_passwd</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>ldap_exop_sync</function></member>
+   <member><function>ldap_exop_whoami</function></member>
+   <member><function>ldap_exop_refresh</function></member>
+   <member><function>ldap_exop_passwd</function></member>
+   <member><function>ldap_parse_result</function></member>
+   <member><function>ldap_parse_exop</function></member>
+  </simplelist>
  </refsect1>
 
-
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml