Fix GH-1408: Deprecation of libxml_disable_entity_loader() should war…

…n about constants which will override the new default behaviour

Based on stale PR GH-1409.
Closes GH-1409.
Closes GH-1408.

Co-authored-by: Andrew Nicols <andrew@nicols.co.uk>

reference/libxml/constants.xml

@@ -46,6 +46,12 @@
     <simpara>
      Default DTD attributes
     </simpara>
+    <caution>
+     <simpara>
+      Enabling loading of DTD attributes will enable fetching of external entities.
+      The <link linkend="constant.libxml-no-xxe"><constant>LIBXML_NO_XXE</constant></link> constant can be used to prevent this (only available in Libxml &gt;= 2.13.0, as of PHP 8.4.0).
+     </simpara>
+    </caution>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.libxml-dtdload">
@@ -57,6 +63,12 @@
     <simpara>
      Load the external subset
     </simpara>
+    <caution>
+     <simpara>
+      Enabling loading of external subsets will enable fetching of external entities.
+      The <link linkend="constant.libxml-no-xxe"><constant>LIBXML_NO_XXE</constant></link> constant can be used to prevent this (only available in Libxml &gt;= 2.13.0, as of PHP 8.4.0).
+     </simpara>
+    </caution>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.libxml-dtdvalid">
@@ -71,6 +83,7 @@
     <caution>
      <simpara>
       Enabling validating the DTD may facilitate XML External Entity (XXE) attacks.
+      The <link linkend="constant.libxml-no-xxe"><constant>LIBXML_NO_XXE</constant></link> constant can be used to prevent this (only available in Libxml &gt;= 2.13.0, as of PHP 8.4.0).
      </simpara>
     </caution>
    </listitem>

reference/libxml/functions/libxml-disable-entity-loader.xml

@@ -20,12 +20,17 @@
   <para>
    Disable/enable the ability to load external entities.
    Note that disabling the loading of external entities may cause general issues
-   with loading XML documents. However, as of libxml 2.9.0 entity substitution
+   with loading XML documents.
+  </para>
+  <para>
+   As of libxml 2.9.0 entity substitution
    is disabled by default, so there is no need to disable the loading of external
    entities,
-   unless there is the need to resolve internal entity references with <constant>LIBXML_NOENT</constant>.
+   unless there is the need to resolve internal entity references with <constant>LIBXML_NOENT</constant> or
+   <constant>LIBXML_DTDVALID</constant>.
    Generally, it is preferable to use <function>libxml_set_external_entity_loader</function>
    to suppress loading of external entities.
+   The <link linkend="constant.libxml-no-xxe"><constant>LIBXML_NO_XXE</constant></link> constant can be used to prevent this as well (only available in Libxml &gt;= 2.13.0, as of PHP 8.4.0).
   </para>
  </refsect1>
 
@@ -100,6 +105,8 @@
     <member><function>libxml_use_internal_errors</function></member>
     <member><function>libxml_set_external_entity_loader</function></member>
     <member><link linkend="libxml.constants">The <constant>LIBXML_NOENT</constant> constant</link></member>
+    <member><link linkend="libxml.constants">The <constant>LIBXML_DTDVALID</constant> constant</link></member>
+    <member><link linkend="libxml.constants">The <constant>LIBXML_NO_XXE</constant> constant</link></member>
    </simplelist>
   </para>
  </refsect1>