diff --git a/language/exceptions.xml b/language/exceptions.xml index 2692dfd9a9fb..2b6a96c1e052 100644 --- a/language/exceptions.xml +++ b/language/exceptions.xml @@ -1,215 +1,34 @@ - - Exceptions - - - Extending Exceptions - - 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. - - - The Built in Exception class - - -]]> - - - - If a class extends the built-in Exception class and re-defines the constructor, it is highly recommended - that it also call parent::__construct() - to ensure all available data has been properly assigned. The __toString() method can be overridden - to provide a custom output when the object is presented as a string. - - - - Exceptions cannot be cloned. Attempting to clone an Exception will result in a - fatal E_ERROR error. - - - - Extending the Exception class - -code}]: {$this->message}\n"; - } - - public function customFunction() { - echo "A custom function for this type of exception\n"; - } -} - - -/** - * Create a class to test the exception - */ -class TestException -{ - public $var; - - const THROW_NONE = 0; - const THROW_CUSTOM = 1; - const THROW_DEFAULT = 2; - - function __construct($avalue = self::THROW_NONE) { - - switch ($avalue) { - case self::THROW_CUSTOM: - // throw custom exception - throw new MyException('1 is an invalid parameter', 5); - break; - - case self::THROW_DEFAULT: - // throw default one. - throw new Exception('2 is not allowed as a parameter', 6); - break; - - default: - // No exception, object will be created. - $this->var = $avalue; - break; - } - } -} - - -// Example 1 -try { - $o = new TestException(TestException::THROW_CUSTOM); -} catch (MyException $e) { // Will be caught - echo "Caught my exception\n", $e; - $e->customFunction(); -} catch (Exception $e) { // Skipped - echo "Caught Default Exception\n", $e; -} - -// Continue execution -var_dump($o); // Null -echo "\n\n"; - - -// Example 2 -try { - $o = new TestException(TestException::THROW_DEFAULT); -} catch (MyException $e) { // Doesn't match this type - echo "Caught my exception\n", $e; - $e->customFunction(); -} catch (Exception $e) { // Will be caught - echo "Caught Default Exception\n", $e; -} - -// Continue execution -var_dump($o); // Null -echo "\n\n"; - - -// Example 3 -try { - $o = new TestException(TestException::THROW_CUSTOM); -} catch (Exception $e) { // Will be caught - echo "Default Exception caught\n", $e; -} - -// Continue execution -var_dump($o); // Null -echo "\n\n"; - - -// Example 4 -try { - $o = new TestException(); -} catch (Exception $e) { // Skipped, no exception - echo "Default Exception caught\n", $e; -} - -// Continue execution -var_dump($o); // TestException -echo "\n\n"; -?> -]]> - - - - - - - PHP has an exception model similar to that of other programming - languages. An exception can be &throw;n, and caught ("&catch;ed") within - PHP. Code may be surrounded in a &try; block, to facilitate the catching - of potential exceptions. Each &try; must have at least one corresponding - &catch; or &finally; block. - - - If an exception is thrown and its current function scope has no &catch; - block, the exception will "bubble up" the call stack to the calling - function until it finds a matching &catch; block. All &finally; blocks it encounters - along the way will be executed. If the call stack is unwound all the way to the - global scope without encountering a matching &catch; block, the program will - terminate with a fatal error unless a global exception handler has been set. - - - The thrown object must be an instance of the - Exception class or a subclass of - Exception. Trying to throw an object that is not - will result in a PHP Fatal Error. - - - As of PHP 8.0.0, the &throw; keyword is an expression and may be used in any expression - context. In prior versions it was a statement and was required to be on its own line. - - - - - + + + Exceptions + + PHP has an exception model similar to that of other programming + languages. An exception can be &throw;n, and caught ("&catch;ed") within + PHP. Code may be surrounded in a &try; block, to facilitate the catching + of potential exceptions. Each &try; must have at least one corresponding + &catch; or &finally; block. + + + If an exception is thrown and its current function scope has no &catch; + block, the exception will "bubble up" the call stack to the calling + function until it finds a matching &catch; block. All &finally; blocks it encounters + along the way will be executed. If the call stack is unwound all the way to the + global scope without encountering a matching &catch; block, the program will + terminate with a fatal error unless a global exception handler has been set. + + + The thrown object must be an &instanceof; Throwable. + Trying to throw an object that is not will result in a PHP Fatal Error. + + + As of PHP 8.0.0, the &throw; keyword is an expression and may be used in any expression + context. In prior versions it was a statement and was required to be on its own line. + + + <literal>catch</literal> A &catch; block defines how to respond to a thrown exception. A &catch; @@ -244,9 +63,9 @@ echo "\n\n"; If not specified, the &catch; block will still execute but will not have access to the thrown object. - + - + <literal>finally</literal> A &finally; block may also be specified after or @@ -262,10 +81,10 @@ echo "\n\n"; is executed. Additionally, if the &finally; block also contains a &return; statement, the value from the &finally; block is returned. - + - - <literal>Global exception handler</literal> + + Global exception handler If an exception is allowed to bubble up to the global scope, it may be caught by a global exception handler if set. The set_exception_handler @@ -273,9 +92,9 @@ echo "\n\n"; other block is invoked. The effect is essentially the same as if the entire program were wrapped in a &try;-&catch; block with that function as the &catch;. - + - + &reftitle.notes; @@ -309,9 +128,9 @@ set_error_handler('exceptions_error_handler'); exceptions. - + - + &reftitle.examples; @@ -531,7 +350,184 @@ try { ]]> - + + + + Extending Exceptions + + 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. + + + The Built in Exception class + + +]]> + + + + If a class extends the built-in Exception class and re-defines the constructor, it is highly recommended + that it also call parent::__construct() + to ensure all available data has been properly assigned. The __toString() method can be overridden + to provide a custom output when the object is presented as a string. + + + + Exceptions cannot be cloned. Attempting to clone an Exception will result in a + fatal E_ERROR error. + + + + Extending the Exception class + + code}]: {$this->message}\n"; + } + + public function customFunction() { + echo "A custom function for this type of exception\n"; + } +} + + +/** + * Create a class to test the exception + */ +class TestException +{ + public $var; + + const THROW_NONE = 0; + const THROW_CUSTOM = 1; + const THROW_DEFAULT = 2; + + function __construct($avalue = self::THROW_NONE) { + + switch ($avalue) { + case self::THROW_CUSTOM: + // throw custom exception + throw new MyException('1 is an invalid parameter', 5); + break; + + case self::THROW_DEFAULT: + // throw default one. + throw new Exception('2 is not allowed as a parameter', 6); + break; + + default: + // No exception, object will be created. + $this->var = $avalue; + break; + } + } +} + + +// Example 1 +try { + $o = new TestException(TestException::THROW_CUSTOM); +} catch (MyException $e) { // Will be caught + echo "Caught my exception\n", $e; + $e->customFunction(); +} catch (Exception $e) { // Skipped + echo "Caught Default Exception\n", $e; +} + +// Continue execution +var_dump($o); // Null +echo "\n\n"; + + +// Example 2 +try { + $o = new TestException(TestException::THROW_DEFAULT); +} catch (MyException $e) { // Doesn't match this type + echo "Caught my exception\n", $e; + $e->customFunction(); +} catch (Exception $e) { // Will be caught + echo "Caught Default Exception\n", $e; +} + +// Continue execution +var_dump($o); // Null +echo "\n\n"; + + +// Example 3 +try { + $o = new TestException(TestException::THROW_CUSTOM); +} catch (Exception $e) { // Will be caught + echo "Default Exception caught\n", $e; +} + +// Continue execution +var_dump($o); // Null +echo "\n\n"; + + +// Example 4 +try { + $o = new TestException(); +} catch (Exception $e) { // Skipped, no exception + echo "Default Exception caught\n", $e; +} + +// Continue execution +var_dump($o); // TestException +echo "\n\n"; +?> +]]> + + +