Exceptions: Difference between revisions
| (8 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
{{Moodle_2.0}} | {{Moodle_2.0}}Exceptions are a common feature in all modern programming languages. They help us to handle exceptional problems that may appear unexpectedly during code execution. | ||
==Overview== | |||
Please keep in mind that exceptions are for something really ''exceptional'', normal code execution flow should not depend on them. | |||
Examples of suitable use are: | |||
* problem writing to directory moodledata directory - this is expected to be always writable | |||
* wrong function/method parameters - coding error which must be fixed by a developer | |||
* inserting data into non-existent database table | |||
Incorrect uses: | |||
* when a user id from the URL does not exist in the database | |||
* using exceptions instead of break in order to terminate loops | |||
* returning results from functions | |||
==Major benefits== | |||
===Less code=== | |||
Many IFs can be eliminated. | |||
===Return values are not mixed with error flags=== | |||
In previous versions database functions were returning false if something went wrong during execution. Sometimes the ''false'' value also meant no value found. | |||
===Recovery after error=== | |||
Previously if something went wrong we either returned false and printed debug info or terminated execution with error(), print_error() or die(). Exceptions allow us to wrap potentially problematic code in try-catch block and recover from exceptions. | |||
Example of suitable use could be admin/cron.php. There were several problems with module scripts terminating and preventing execution of other parts of cron script. Now we can wrap all calls to cron functions in try-catch block and recover from problems in individual activities or 3rd party code. | |||
==Exception hierarchy== | |||
[[Image:Exceptions.png]] | |||
===moodle_exception=== | |||
Unknown type of problem, also used by print_error() and error() functions. Please try to find some more suitable exception type if possible. | |||
Defined in lib/setuplib.php for now. | |||
===coding_exception=== | |||
General exception indicating incorrect use of function, bogus parameters, etc. Most probably a typo or developer did not understand the inline docs. Use especially in library functions when you think that the developer should be notified. The hint in constructor is not expected to be localised. | |||
Defined in lib/setuplib.php for now. | |||
===ddl_exception=== | |||
Base class for all exceptions that may be thrown during manipulation of database structure. See linked page for details. | |||
===dml_exception=== | |||
Base class for all exceptions that may be thrown during normal database access. See linked page for details. | |||
===file_exception=== | |||
Base class for file storage related problems. | |||
==See also== | ==See also== | ||
| Line 10: | Line 53: | ||
* [[DML exceptions|DML exceptions]]: Use of exceptions in DML layer | * [[DML exceptions|DML exceptions]]: Use of exceptions in DML layer | ||
* [[DDL exceptions|DDL exceptions]]: Use of exceptions in DDL layer | * [[DDL exceptions|DDL exceptions]]: Use of exceptions in DDL layer | ||
* [[File storage exceptions|File exceptions]]: Use of exceptions in file storage layer | |||
Latest revision as of 01:32, 28 November 2008
Moodle 2.0
Exceptions are a common feature in all modern programming languages. They help us to handle exceptional problems that may appear unexpectedly during code execution.
Overview
Please keep in mind that exceptions are for something really exceptional, normal code execution flow should not depend on them.
Examples of suitable use are:
- problem writing to directory moodledata directory - this is expected to be always writable
- wrong function/method parameters - coding error which must be fixed by a developer
- inserting data into non-existent database table
Incorrect uses:
- when a user id from the URL does not exist in the database
- using exceptions instead of break in order to terminate loops
- returning results from functions
Major benefits
Less code
Many IFs can be eliminated.
Return values are not mixed with error flags
In previous versions database functions were returning false if something went wrong during execution. Sometimes the false value also meant no value found.
Recovery after error
Previously if something went wrong we either returned false and printed debug info or terminated execution with error(), print_error() or die(). Exceptions allow us to wrap potentially problematic code in try-catch block and recover from exceptions.
Example of suitable use could be admin/cron.php. There were several problems with module scripts terminating and preventing execution of other parts of cron script. Now we can wrap all calls to cron functions in try-catch block and recover from problems in individual activities or 3rd party code.
Exception hierarchy
moodle_exception
Unknown type of problem, also used by print_error() and error() functions. Please try to find some more suitable exception type if possible.
Defined in lib/setuplib.php for now.
coding_exception
General exception indicating incorrect use of function, bogus parameters, etc. Most probably a typo or developer did not understand the inline docs. Use especially in library functions when you think that the developer should be notified. The hint in constructor is not expected to be localised.
Defined in lib/setuplib.php for now.
ddl_exception
Base class for all exceptions that may be thrown during manipulation of database structure. See linked page for details.
dml_exception
Base class for all exceptions that may be thrown during normal database access. See linked page for details.
file_exception
Base class for file storage related problems.
See also
- PHP Manual - Exceptions
- DML exceptions: Use of exceptions in DML layer
- DDL exceptions: Use of exceptions in DDL layer
- File exceptions: Use of exceptions in file storage layer
