Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Exceptions: Difference between revisions

From MoodleDocs
 
(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.


TODO: add more info here, explanation and same examples.
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

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