Source of: /manual/en/language.exceptions.extending.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/language.exceptions.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'language.exceptions.extending.php',
1 => 'Extending Exceptions',
),
'up' =>
array (
0 => 'language.exceptions.php',
1 => 'Exceptions',
),
'prev' =>
array (
0 => 'language.exceptions.php',
1 => 'Exceptions',
),
'next' =>
array (
0 => 'language.references.php',
1 => 'References Explained',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="language.exceptions.extending" class="sect1">
<h2 class="title">Extending Exceptions</h2>
<p class="para">
A User defined Exception class can be defined by extending the built-in
Exception class. The members and properties below, show what is accessible
within the child class that derives from the built-in Exception class.
</p>
<div class="example">
<p><b>Example #1 The Built in Exception class</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">Exception<br /></span><span style="color: #007700">{<br /> protected </span><span style="color: #0000BB">$message </span><span style="color: #007700">= </span><span style="color: #DD0000">'Unknown exception'</span><span style="color: #007700">; </span><span style="color: #FF8000">// exception message<br /> </span><span style="color: #007700">private </span><span style="color: #0000BB">$string</span><span style="color: #007700">; </span><span style="color: #FF8000">// __toString cache<br /> </span><span style="color: #007700">protected </span><span style="color: #0000BB">$code </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">; </span><span style="color: #FF8000">// user defined exception code<br /> </span><span style="color: #007700">protected </span><span style="color: #0000BB">$file</span><span style="color: #007700">; </span><span style="color: #FF8000">// source filename of exception<br /> </span><span style="color: #007700">protected </span><span style="color: #0000BB">$line</span><span style="color: #007700">; </span><span style="color: #FF8000">// source line of exception<br /> </span><span style="color: #007700">private </span><span style="color: #0000BB">$trace</span><span style="color: #007700">; </span><span style="color: #FF8000">// backtrace<br /> </span><span style="color: #007700">private </span><span style="color: #0000BB">$previous</span><span style="color: #007700">; </span><span style="color: #FF8000">// previous exception if nested exception<br /><br /> </span><span style="color: #007700">public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$message </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">, </span><span style="color: #0000BB">$code </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #0000BB">Exception $previous </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">);<br /><br /> final private function </span><span style="color: #0000BB">__clone</span><span style="color: #007700">(); </span><span style="color: #FF8000">// Inhibits cloning of exceptions.<br /><br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getMessage</span><span style="color: #007700">(); </span><span style="color: #FF8000">// message of exception<br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getCode</span><span style="color: #007700">(); </span><span style="color: #FF8000">// code of exception<br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getFile</span><span style="color: #007700">(); </span><span style="color: #FF8000">// source filename<br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getLine</span><span style="color: #007700">(); </span><span style="color: #FF8000">// source line<br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getTrace</span><span style="color: #007700">(); </span><span style="color: #FF8000">// an array of the backtrace()<br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getPrevious</span><span style="color: #007700">(); </span><span style="color: #FF8000">// previous exception<br /> </span><span style="color: #007700">final public function </span><span style="color: #0000BB">getTraceAsString</span><span style="color: #007700">(); </span><span style="color: #FF8000">// formatted string of trace<br /><br /> /* Overrideable */<br /> </span><span style="color: #007700">public function </span><span style="color: #0000BB">__toString</span><span style="color: #007700">(); </span><span style="color: #FF8000">// formatted string for display<br /></span><span style="color: #007700">}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<p class="para">
If a class extends the built-in Exception class and re-defines the <a href="language.oop5.decon.php" class="link">constructor</a>, it is highly recommended
that it also call <a href="language.oop5.paamayim-nekudotayim.php" class="link">parent::__construct()</a>
to ensure all available data has been properly assigned. The <a href="language.oop5.magic.php" class="link">__toString()</a> method can be overridden
to provide a custom output when the object is presented as a string.
</p>
<blockquote><p><b class="note">Note</b>:
Exceptions cannot be cloned. Attempting to <a href="language.oop5.cloning.php" class="link">clone</a> an Exception will result in a
<i>E_FATAL</i> error.
<br />
</p></blockquote>
<div class="example">
<p><b>Example #2 Extending the Exception class</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * Define a custom exception class<br /> */<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">MyException </span><span style="color: #007700">extends </span><span style="color: #0000BB">Exception<br /></span><span style="color: #007700">{<br /> </span><span style="color: #FF8000">// Redefine the exception so message isn't optional<br /> </span><span style="color: #007700">public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$message</span><span style="color: #007700">, </span><span style="color: #0000BB">$code </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #0000BB">Exception $previous </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// some code<br /> <br /> // make sure everything is assigned properly<br /> </span><span style="color: #0000BB">parent</span><span style="color: #007700">::</span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$message</span><span style="color: #007700">, </span><span style="color: #0000BB">$code</span><span style="color: #007700">, </span><span style="color: #0000BB">$previous</span><span style="color: #007700">);<br /> }<br /><br /> </span><span style="color: #FF8000">// custom string representation of object<br /> </span><span style="color: #007700">public function </span><span style="color: #0000BB">__toString</span><span style="color: #007700">() {<br /> return </span><span style="color: #0000BB">__CLASS__ </span><span style="color: #007700">. </span><span style="color: #DD0000">": [</span><span style="color: #007700">{</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">code</span><span style="color: #007700">}</span><span style="color: #DD0000">]: </span><span style="color: #007700">{</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">message</span><span style="color: #007700">}</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /> }<br /><br /> public function </span><span style="color: #0000BB">customFunction</span><span style="color: #007700">() {<br /> echo </span><span style="color: #DD0000">"A custom function for this type of exception\n"</span><span style="color: #007700">;<br /> }<br />}<br /><br /><br /></span><span style="color: #FF8000">/**<br /> * Create a class to test the exception<br /> */<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">TestException<br /></span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$var</span><span style="color: #007700">;<br /><br /> const </span><span style="color: #0000BB">THROW_NONE </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /> const </span><span style="color: #0000BB">THROW_CUSTOM </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /> const </span><span style="color: #0000BB">THROW_DEFAULT </span><span style="color: #007700">= </span><span style="color: #0000BB">2</span><span style="color: #007700">;<br /><br /> function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$avalue </span><span style="color: #007700">= </span><span style="color: #0000BB">self</span><span style="color: #007700">::</span><span style="color: #0000BB">THROW_NONE</span><span style="color: #007700">) {<br /><br /> switch (</span><span style="color: #0000BB">$avalue</span><span style="color: #007700">) {<br /> case </span><span style="color: #0000BB">self</span><span style="color: #007700">::</span><span style="color: #0000BB">THROW_CUSTOM</span><span style="color: #007700">:<br /> </span><span style="color: #FF8000">// throw custom exception<br /> </span><span style="color: #007700">throw new </span><span style="color: #0000BB">MyException</span><span style="color: #007700">(</span><span style="color: #DD0000">'1 is an invalid parameter'</span><span style="color: #007700">, </span><span style="color: #0000BB">5</span><span style="color: #007700">);<br /> break;<br /><br /> case </span><span style="color: #0000BB">self</span><span style="color: #007700">::</span><span style="color: #0000BB">THROW_DEFAULT</span><span style="color: #007700">:<br /> </span><span style="color: #FF8000">// throw default one.<br /> </span><span style="color: #007700">throw new </span><span style="color: #0000BB">Exception</span><span style="color: #007700">(</span><span style="color: #DD0000">'2 is not allowed as a parameter'</span><span style="color: #007700">, </span><span style="color: #0000BB">6</span><span style="color: #007700">);<br /> break;<br /><br /> default: <br /> </span><span style="color: #FF8000">// No exception, object will be created.<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">var </span><span style="color: #007700">= </span><span style="color: #0000BB">$avalue</span><span style="color: #007700">;<br /> break;<br /> }<br /> }<br />}<br /><br /><br /></span><span style="color: #FF8000">// Example 1<br /></span><span style="color: #007700">try {<br /> </span><span style="color: #0000BB">$o </span><span style="color: #007700">= new </span><span style="color: #0000BB">TestException</span><span style="color: #007700">(</span><span style="color: #0000BB">TestException</span><span style="color: #007700">::</span><span style="color: #0000BB">THROW_CUSTOM</span><span style="color: #007700">);<br />} catch (</span><span style="color: #0000BB">MyException $e</span><span style="color: #007700">) { </span><span style="color: #FF8000">// Will be caught<br /> </span><span style="color: #007700">echo </span><span style="color: #DD0000">"Caught my exception\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">customFunction</span><span style="color: #007700">();<br />} catch (</span><span style="color: #0000BB">Exception $e</span><span style="color: #007700">) { </span><span style="color: #FF8000">// Skipped<br /> </span><span style="color: #007700">echo </span><span style="color: #DD0000">"Caught Default Exception\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #FF8000">// Continue execution<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$o</span><span style="color: #007700">); </span><span style="color: #FF8000">// Null<br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">"\n\n"</span><span style="color: #007700">;<br /><br /><br /></span><span style="color: #FF8000">// Example 2<br /></span><span style="color: #007700">try {<br /> </span><span style="color: #0000BB">$o </span><span style="color: #007700">= new </span><span style="color: #0000BB">TestException</span><span style="color: #007700">(</span><span style="color: #0000BB">TestException</span><span style="color: #007700">::</span><span style="color: #0000BB">THROW_DEFAULT</span><span style="color: #007700">);<br />} catch (</span><span style="color: #0000BB">MyException $e</span><span style="color: #007700">) { </span><span style="color: #FF8000">// Doesn't match this type<br /> </span><span style="color: #007700">echo </span><span style="color: #DD0000">"Caught my exception\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">customFunction</span><span style="color: #007700">();<br />} catch (</span><span style="color: #0000BB">Exception $e</span><span style="color: #007700">) { </span><span style="color: #FF8000">// Will be caught<br /> </span><span style="color: #007700">echo </span><span style="color: #DD0000">"Caught Default Exception\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #FF8000">// Continue execution<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$o</span><span style="color: #007700">); </span><span style="color: #FF8000">// Null<br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">"\n\n"</span><span style="color: #007700">;<br /><br /><br /></span><span style="color: #FF8000">// Example 3<br /></span><span style="color: #007700">try {<br /> </span><span style="color: #0000BB">$o </span><span style="color: #007700">= new </span><span style="color: #0000BB">TestException</span><span style="color: #007700">(</span><span style="color: #0000BB">TestException</span><span style="color: #007700">::</span><span style="color: #0000BB">THROW_CUSTOM</span><span style="color: #007700">);<br />} catch (</span><span style="color: #0000BB">Exception $e</span><span style="color: #007700">) { </span><span style="color: #FF8000">// Will be caught<br /> </span><span style="color: #007700">echo </span><span style="color: #DD0000">"Default Exception caught\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #FF8000">// Continue execution<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$o</span><span style="color: #007700">); </span><span style="color: #FF8000">// Null<br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">"\n\n"</span><span style="color: #007700">;<br /><br /><br /></span><span style="color: #FF8000">// Example 4<br /></span><span style="color: #007700">try {<br /> </span><span style="color: #0000BB">$o </span><span style="color: #007700">= new </span><span style="color: #0000BB">TestException</span><span style="color: #007700">();<br />} catch (</span><span style="color: #0000BB">Exception $e</span><span style="color: #007700">) { </span><span style="color: #FF8000">// Skipped, no exception<br /> </span><span style="color: #007700">echo </span><span style="color: #DD0000">"Default Exception caught\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #FF8000">// Continue execution<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$o</span><span style="color: #007700">); </span><span style="color: #FF8000">// TestException<br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">"\n\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div><?php manual_footer(); ?>