<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <title>Extending Exceptions</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="language.exceptions.html">Exceptions</a></div> <div class="next" style="text-align: right; float: right;"><a href="language.generators.html">Generators</a></div> <div class="up"><a href="language.exceptions.html">Exceptions</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><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" id="example-272"> <p><strong>Example #1 The Built in Exception class</strong></p> <div class="example-contents"> <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.html" class="link">constructor</a>, it is highly recommended that it also call <a href="language.oop5.paamayim-nekudotayim.html" class="link">parent::__construct()</a> to ensure all available data has been properly assigned. The <a href="language.oop5.magic.html" class="link">__toString()</a> method can be overridden to provide a custom output when the object is presented as a string. </p> <blockquote class="note"><p><strong class="note">Note</strong>: <p class="para"> Exceptions cannot be cloned. Attempting to <a href="language.oop5.cloning.html" class="link">clone</a> an Exception will result in a fatal <strong><code>E_ERROR</code></strong> error. </p> </p></blockquote> <div class="example" id="example-273"> <p><strong>Example #2 Extending the Exception class (PHP 5.3.0+)</strong></p> <div class="example-contents"> <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> <blockquote class="note"><p><strong class="note">Note</strong>: <p class="para"> Versions of PHP 5, prior to PHP 5.3.0 do not support nesting of exceptions. The following code fragment can be used as a replacement MyException class if you wish to run this example. </p> <div class="example-contents"> <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">) {<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">);<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 /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </p></blockquote> </div> </div><hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="language.exceptions.html">Exceptions</a></div> <div class="next" style="text-align: right; float: right;"><a href="language.generators.html">Generators</a></div> <div class="up"><a href="language.exceptions.html">Exceptions</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>