PHP 8.4: xml_set_*() deprecations and changes (#4067)

Author: Girgias

language-snippets.ent

@@ -4488,7 +4488,13 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
 </varlistentry>'>
 
 <!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
- If &null; or an empty string is passed, the handler is reset to its default state.
+ If &null; is passed, the handler is reset to its default state.
+ <warning>
+  <simpara>
+    An empty string will also reset the handler,
+    however this is deprecated as of PHP 8.4.0.
+  </simpara>
+ </warning>
 </para>
 <para xmlns="http://docbook.org/ns/docbook">
  If <parameter>handler</parameter> is a <type>callable</type>,
@@ -4498,7 +4504,23 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
  If <parameter>handler</parameter> is a <type>string</type>,
  it can be the name of a method of an object set with
  <function>xml_set_object</function>.
-</para>'>
+ <warning>
+  <simpara>
+   This is deprecated as of PHP 8.4.0.
+  </simpara>
+ </warning>
+</para>
+<warning xmlns="http://docbook.org/ns/docbook">
+ <simpara>
+  As of PHP 8.4.0, the callable is checked to be valid while setting the handler,
+  not when it is called.
+  This means that <function>xml_set_object</function> must be called prior to
+  setting a method string as the callback.
+  However, as this behaviour is also deprecated as of PHP 8.4.0,
+  using a proper <type>callable</type> for the method is recommended instead.
+ </simpara>
+</warning>
+'>
 
 <!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
  <term><parameter>parser</parameter></term>
@@ -4509,6 +4531,22 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
  </listitem>
 </varlistentry>'>
 
+<!ENTITY xml.changelog.handler-param '<row xmlns="http://docbook.org/ns/docbook">
+ <entry>8.4.0</entry>
+ <entry>
+  Passing a non-<type>callable</type> <type>string</type> to
+  <parameter>handler</parameter> is now deprecated,
+  use a proper callable for methods, or &null; to reset the handler.
+ </entry>
+</row>
+<row xmlns="http://docbook.org/ns/docbook">
+ <entry>8.4.0</entry>
+ <entry>
+  The validity of <parameter>handler</parameter> as a <type>callable</type>
+  is now checked when setting the handler instead of checking when calling it.
+ </entry>
+</row>'>
+
 <!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.0.0</entry>
  <entry>

reference/xml/functions/xml-set-character-data-handler.xml

@@ -76,7 +76,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>

reference/xml/functions/xml-set-default-handler.xml

@@ -75,7 +75,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>

reference/xml/functions/xml-set-element-handler.xml

@@ -125,7 +125,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>

reference/xml/functions/xml-set-end-namespace-decl-handler.xml

@@ -80,7 +80,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>

reference/xml/functions/xml-set-external-entity-ref-handler.xml

@@ -111,7 +111,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
      <row>
       <entry>7.3.0</entry>
       <entry>

reference/xml/functions/xml-set-notation-decl-handler.xml

@@ -116,7 +116,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>

reference/xml/functions/xml-set-object.xml

@@ -5,6 +5,10 @@
   <refname>xml_set_object</refname>
   <refpurpose>Use XML Parser within an object</refpurpose>
  </refnamediv>
+
+ <refsynopsisdiv>
+  &warn.deprecated.function-8-4-0;
+ </refsynopsisdiv>
 
  <refsect1 role="description">
   &reftitle.description;
@@ -63,6 +67,14 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       This function is now deprecated,
+       instead pass proper <type>callable</type> values to
+       <function>xml_set_</function>
+      </entry>
+     </row>
       &xml.changelog.parser-param;
     </tbody>
    </tgroup>

reference/xml/functions/xml-set-processing-instruction-handler.xml

@@ -104,7 +104,8 @@ data
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>

reference/xml/functions/xml-set-start-namespace-decl-handler.xml

@@ -84,7 +84,8 @@
      </row>
     </thead>
     <tbody>
-      &xml.changelog.parser-param;
+     &xml.changelog.handler-param;
+     &xml.changelog.parser-param;
     </tbody>
    </tgroup>
   </informaltable>