[doc-en] master: Add warning about cloning exceptions (#5276)
| From: | Louis-Arnaud via GitHub | 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>