[doc-en] master: Document the PHP 8.5 new warnings and exceptions (#5838)

Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-08T14:42:04+02:00 Commit: https://github.com/php/doc-en/commit/9ac246c4cf437dae2bf18fd3714545d7a0a51091 Raw diff: https://github.com/php/doc-en/commit/9ac246c4cf437dae2bf18fd3714545d7a0a51091.diff Document the PHP 8.5 new warnings and exceptions (#5838) * Document the PHP 8.5 new warnings and exceptions bzcompress() and pcntl_exec() gain an errors section and a changelog for the ValueErrors they now throw; finfo_file(), the mysqli constructor, session_start() and session_write_close() gain the matching changelog rows. * Add some links * Document the SimpleXML and Tidy 8.5 errors SimpleXMLElement::xpath() now warns and returns false on a non-node-set result; the tidy constructor and parse methods now throw on invalid configuration entries. * Update reference/simplexml/simplexmlelement/xpath.xml Co-authored-by: Kamil Tekiela <tekiela246@gmail.com> * Update reference/simplexml/simplexmlelement/xpath.xml Co-authored-by: Kamil Tekiela <tekiela246@gmail.com> * Add the errors sections and align the warning wording The new exceptions were only recorded in the changelog tables, which say when the behaviour changed, not what the function throws. Describe them in the errors section of each page as well, and name E_WARNING explicitly in session_write_close() as the rest of the pull request already does. --------- Co-authored-by: Kamil Tekiela <tekiela246@gmail.com> Changed paths: M reference/bzip2/functions/bzcompress.xml M reference/fileinfo/functions/finfo-file.xml M reference/mysqli/mysqli/construct.xml M reference/pcntl/functions/pcntl-exec.xml M reference/session/functions/session-start.xml M reference/session/functions/session-write-close.xml M reference/simplexml/simplexmlelement/xpath.xml M reference/tidy/tidy/construct.xml M reference/tidy/tidy/parsefile.xml M reference/tidy/tidy/parsestring.xml Diff: diff --git a/reference/bzip2/functions/bzcompress.xml b/reference/bzip2/functions/bzcompress.xml index 89302c27c90e..14924a957d4d 100644 --- a/reference/bzip2/functions/bzcompress.xml +++ b/reference/bzip2/functions/bzcompress.xml @@ -61,6 +61,39 @@ The compressed string, or an error number if an error occurred. </simpara> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + As of PHP 8.5.0, a <exceptionname>ValueError</exceptionname> is thrown if + <parameter>block_size</parameter> is not between 1 and 9, or if + <parameter>work_factor</parameter> is not between 0 and 250. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + A <exceptionname>ValueError</exceptionname> is now thrown if + <parameter>block_size</parameter> is not between 1 and 9, or if + <parameter>work_factor</parameter> is not between 0 and 250. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <example> @@ -80,6 +113,8 @@ echo $bzstr; &reftitle.seealso; <simplelist> <member><function>bzdecompress</function></member> + <member><function>bzopen</function></member> + <member><function>gzcompress</function></member> </simplelist> </refsect1> </refentry> diff --git a/reference/fileinfo/functions/finfo-file.xml b/reference/fileinfo/functions/finfo-file.xml index 09c2172557c6..0e9c04b29455 100644 --- a/reference/fileinfo/functions/finfo-file.xml +++ b/reference/fileinfo/functions/finfo-file.xml @@ -74,6 +74,16 @@ </simpara> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if + <parameter>filename</parameter> contains any null bytes. + Prior to PHP 8.5.0, a <exceptionname>TypeError</exceptionname> was thrown + instead. + </simpara> + </refsect1> + <refsect1 role="changelog"> &reftitle.changelog; <informaltable> @@ -85,6 +95,14 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + A <exceptionname>ValueError</exceptionname> is now thrown instead of a + <exceptionname>TypeError</exceptionname> when <parameter>filename</parameter> + contains null bytes. + </entry> + </row> &fileinfo.changelog.finfo-object; <row> <entry>8.0.0</entry> diff --git a/reference/mysqli/mysqli/construct.xml b/reference/mysqli/mysqli/construct.xml index 9e2f66c3ef26..d8cc3124b99e 100644 --- a/reference/mysqli/mysqli/construct.xml +++ b/reference/mysqli/mysqli/construct.xml @@ -141,6 +141,10 @@ <refsect1 role="errors"> &reftitle.errors; &mysqli.conditionalexception; + <simpara> + As of PHP 8.5.0, calling the constructor on an already-constructed object + throws an <exceptionname>Error</exceptionname>. + </simpara> </refsect1> <refsect1 role="changelog"> @@ -155,6 +159,13 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + Calling the constructor on an already-constructed object now throws + an <exceptionname>Error</exceptionname>. + </entry> + </row> <row> <entry>8.1.0</entry> <entry> diff --git a/reference/pcntl/functions/pcntl-exec.xml b/reference/pcntl/functions/pcntl-exec.xml index ddab4cb3331c..e637aedf9fbb 100644 --- a/reference/pcntl/functions/pcntl-exec.xml +++ b/reference/pcntl/functions/pcntl-exec.xml @@ -66,6 +66,49 @@ </simpara> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + As of PHP 8.5.0, a <exceptionname>ValueError</exceptionname> is thrown if any + entry of <parameter>args</parameter> contains a null byte, or if any + entry or key of <parameter>env_vars</parameter> contains a null byte. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + A <exceptionname>ValueError</exceptionname> is now thrown if any entry of + <parameter>args</parameter> contains a null byte, or if any entry or + key of <parameter>env_vars</parameter> contains a null byte. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>pcntl_fork</function></member> + <member><function>pcntl_waitpid</function></member> + <member><function>exec</function></member> + <member><function>proc_open</function></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file Local variables: diff --git a/reference/session/functions/session-start.xml b/reference/session/functions/session-start.xml index 0e690783eb58..41c61274f56e 100644 --- a/reference/session/functions/session-start.xml +++ b/reference/session/functions/session-start.xml @@ -76,6 +76,20 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + As of PHP 8.5.0, throws a <exceptionname>ValueError</exceptionname> if + <parameter>options</parameter> has any non-string key. + </simpara> + <simpara> + As of PHP 8.5.0, throws a <exceptionname>TypeError</exceptionname> if the + <literal>read_and_close</literal> option is not of type <type>string</type>, + <type>int</type> or <type>bool</type>, or if its value cannot be interpreted + as an <type>int</type>. + </simpara> + </refsect1> + <refsect1 role="changelog"> &reftitle.changelog; <para> @@ -88,6 +102,16 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if the + <parameter>options</parameter> array has non-string keys, and a + <exceptionname>TypeError</exceptionname> if the + <literal>read_and_close</literal> value is not compatible with + <type>int</type>. + </entry> + </row> <row> <entry>7.1.0</entry> <entry> diff --git a/reference/session/functions/session-write-close.xml b/reference/session/functions/session-write-close.xml index af1fa22ec4ec..5f3d6fb00879 100644 --- a/reference/session/functions/session-write-close.xml +++ b/reference/session/functions/session-write-close.xml @@ -49,6 +49,14 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + If <varname>$_SESSION</varname> contains a key with a pipe character + (<literal>|</literal>), an <constant>E_WARNING</constant> is now emitted. Previously, this + would silently fail to write the session data. + </entry> + </row> <row> <entry>7.2.0</entry> <entry> @@ -63,13 +71,11 @@ <refsect1 role="seealso"> &reftitle.seealso; - <para> - <simplelist> - <member> - The <function>session_register_shutdown</function> - </member> - </simplelist> - </para> + <simplelist> + <member><function>session_register_shutdown</function></member> + <member><function>session_start</function></member> + <member><function>session_abort</function></member> + </simplelist> </refsect1> </refentry> diff --git a/reference/simplexml/simplexmlelement/xpath.xml b/reference/simplexml/simplexmlelement/xpath.xml index 850e067db3b0..2466580e704c 100644 --- a/reference/simplexml/simplexmlelement/xpath.xml +++ b/reference/simplexml/simplexmlelement/xpath.xml @@ -40,6 +40,35 @@ Returns an <type>array</type> of SimpleXMLElement objects on success; or &null; or &false; in case of an error. </para> + <simpara> + As of PHP 8.5.0, if the XPath expression returns something other than a node set + (e.g. a boolean or number), an <constant>E_WARNING</constant> is emitted and + &false; is returned instead of silently returning an empty array. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + If the XPath expression returns something other than a node set, an + <constant>E_WARNING</constant> is now emitted and &false; is returned. + Previously, an empty array was returned silently. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </refsect1> <refsect1 role="examples"> diff --git a/reference/tidy/tidy/construct.xml b/reference/tidy/tidy/construct.xml index 4a9ee574bdd6..e6bde54306ab 100644 --- a/reference/tidy/tidy/construct.xml +++ b/reference/tidy/tidy/construct.xml @@ -92,6 +92,16 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if + <parameter>config</parameter> contains an unknown option or attempts to + set a read-only one, and a <exceptionname>TypeError</exceptionname> if a + configuration key is not a string, or if an option does not accept the + given value. + </entry> + </row> <row> <entry>8.4.0</entry> <entry> diff --git a/reference/tidy/tidy/parsefile.xml b/reference/tidy/tidy/parsefile.xml index 842e30e08a7a..76b4c229f400 100644 --- a/reference/tidy/tidy/parsefile.xml +++ b/reference/tidy/tidy/parsefile.xml @@ -105,6 +105,16 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if + <parameter>config</parameter> contains an unknown option or attempts to + set a read-only one, and a <exceptionname>TypeError</exceptionname> if a + configuration key is not a string, or if an option does not accept the + given value. + </entry> + </row> <row> <entry>8.0.0</entry> <entry> diff --git a/reference/tidy/tidy/parsestring.xml b/reference/tidy/tidy/parsestring.xml index 03d05222b742..1e2c5a80e796 100644 --- a/reference/tidy/tidy/parsestring.xml +++ b/reference/tidy/tidy/parsestring.xml @@ -92,6 +92,16 @@ </row> </thead> <tbody> + <row> + <entry>8.5.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if + <parameter>config</parameter> contains an unknown option or attempts to + set a read-only one, and a <exceptionname>TypeError</exceptionname> if a + configuration key is not a string, or if an option does not accept the + given value. + </entry> + </row> <row> <entry>8.0.0</entry> <entry>