Catching Unexpected Faults May 14, 2022
Starting v19.1, Gyroscope supports additional error trapping methods. A fault log report is also included.
On the syntax level, this might seem to be a replacement for apperror:
function do_something(){
if (something_wrong) apperror("Error: reason");
}
New code:
function do_something(){
if (something_wrong) throw new ErrorException("Error: reason");
}
When the latter method is used, an entry is created in the fault log. The apperror function is still called internally as the final resolution.
Conceptually, the "something wrong" in the two cases have different nature. When apperror is called directly, it often means a user error that takes place on the server side. For example, a record collision, a permission-based rejection, etc. The program is behaving as expected.
When an external component is involved, the behavior of the program becomes less predictable. Therefore instead of calling it a generic Exception, it's called a "fault". For example, if a web service fails, we need to relay this information to the user. In the eyes of an end user, the behavior is the same as an apperror call. But the owner or the admin of the app might want to trap such external failure.
In a more complex project where third-party components are used, a general Exception might be thrown as well. Now Gyroscope has an overall catch in case an exception is not handled.
Another quick way to delineate the two use cases is by deciding whether the admin needs to know about the error. apperror only notifies the end user, and often that's enough. But if the admin also needs take a deferred action, such error should be logged, in which case an Exception trap is more suitable.
A Fault Log entry contains the offending file, code line, invoking function and call arguments.
Version 19.1 also introduced a FaultException type for storing diagnostic data. The failed web service might return additional error codes, or forensic snippets for reproducing the error. One example would be a non-parse-able response.
throw new FaultException("message to user","internal diagnostic data");
Migration Notes
The following files must be patched:
- the faults table
- lb.php (faults table constant for vendor portals)
- forminput.php (FaultException class, logfault function)
- myservices.php (try-catch block around the cmd switch)
- settings.php (faultlog user permission)
- rptfaultlog.inc.php (fault log report)
The changes are also tracked as 2c112eb, 2fdaaa2 and fd4821f on GitHub.
