[doc-en] master: Add warning about cloning exceptions (#5276)

From: Date: Tue, 01 Sep 2026 13:32:25 +0000
Subject: [doc-en] master: Add warning about cloning exceptions (#5276)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23688@lists.php.net to get a copy of this message
Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-01T15:32:22+02:00 Commit: https://github.com/php/doc-en/commit/62562234f18ac091ecd1fb648ac0d56172c74a1a Raw diff: https://github.com/php/doc-en/commit/62562234f18ac091ecd1fb648ac0d56172c74a1a.diff Add warning about cloning exceptions (#5276) Changed paths: M language/exceptions.xml M language/predefined/exception/clone.xml Diff: diff --git a/language/exceptions.xml b/language/exceptions.xml index 3e25163b1b3f..c284e26c36d5 100644 --- a/language/exceptions.xml +++ b/language/exceptions.xml @@ -409,7 +409,7 @@ string(6) "Fourth" <?php class Exception implements Throwable { - protected $message = 'Unknown exception'; // exception message + protected $message = ''; // exception message private $string; // __toString cache protected $code = 0; // user defined exception code protected $file; // source filename of exception @@ -419,7 +419,7 @@ class Exception implements Throwable public function __construct($message = '', $code = 0, ?Throwable $previous = null); - final private function __clone(); // Inhibits cloning of exceptions. + private function __clone(); // Inhibits cloning of exceptions. final public function getMessage(); // message of exception final public function getCode(); // code of exception @@ -445,11 +445,12 @@ class Exception implements Throwable to provide a custom output when the object is presented as a string. </para> <note> - <para> + <simpara> Exceptions cannot be cloned. Attempting to <link - linkend="language.oop5.cloning">clone</link> an Exception will result in a - fatal <constant>E_ERROR</constant> error. - </para> + linkend="language.oop5.cloning">clone</link> an exception throws an + <exceptionname>Error</exceptionname>, even if a subclass declares its own + <link linkend="object.clone">__clone()</link> method. + </simpara> </note> <example> <title>Extending the Exception class</title> diff --git a/language/predefined/exception/clone.xml b/language/predefined/exception/clone.xml index 527f9b90bd0f..db137381dcf3 100644 --- a/language/predefined/exception/clone.xml +++ b/language/predefined/exception/clone.xml @@ -12,10 +12,18 @@ <modifier>private</modifier> <type>void</type><methodname>Exception::__clone</methodname> <void/> </methodsynopsis> - <para> - <classname>Exception</classname>s cannot be cloned, - and attempting to do so will throw an <classname>Error</classname>. - </para> + <simpara> + Exceptions do not support cloning; this method exists only to prevent it. + </simpara> + <warning> + <simpara> + Exceptions cannot be cloned, whether they are instances of + <exceptionname>Exception</exceptionname> or of a subclass. + Attempting to <link linkend="language.oop5.cloning">clone</link> an + exception throws an <exceptionname>Error</exceptionname>, which may be + caught. + </simpara> + </warning> </refsect1> <refsect1 role="parameters"> @@ -51,7 +59,12 @@ <row> <entry>8.1.0</entry> <entry> - <methodname>Exception::__clone</methodname> is no longer final. + <methodname>Exception::__clone</methodname> is no longer declared + <modifier>final</modifier>, because + <link linkend="language.oop5.final">declaring a + <modifier>private</modifier> method + <modifier>final</modifier></link> emits a warning as of PHP 8.0.0. + Exceptions remain uncloneable. </entry> </row> </tbody>

« previous php.doc.cvs (#23688) next »