Custom DF_REST exceptions
What I did
- Created a new library file
DF_Rest_Exceptions.php
to hold custom exception classes for use with DF_Rest_Controller.- Included it into
DF_Rest_Controller.php
.
- Included it into
- Moved the existing empty
DF_REST_Where_Exception
class into that file from the controller. - Added a new
DF_Rest_FatalityReport
exception- For use when checks in application code have identified a fatal error, and the code is wanting to pass one or more user-friendly messages back out to be displayed at the front end.
- Can also be passed a message and extra info to be sent to the developer (i.e. standard zon-type error notification email).
- Will throw a base Exception if no error messages are supplied, but will send notification email first if that was requested.
- Added a new
DF_REST_ValidationFailure
exception- For use when backend code has found a validation problem with input data.
- Added a general-purpose
handle_api_method_exception()
method toDF_Rest_Controller
, which can be used in a catch-all Exception handler in top-level API methods. e.g.:
public function donated_post()
{
try
{
$success_message = $this->_donated_before();
$this->response(array(
'result' => 'success',
'message' => array($success_message)
));
}
catch (Exception $e)
{
$this->handle_api_method_exception($e);
}
}
- The
handle_api_method_exception()
method will take suitable default actions in terms of issuing a response to the front end, checking for and handling the two new custom exception classes above. The intent here is that lower-level code code called by a top-level API method such as the one above can throwDF_Rest_FatalityReport
s andDF_REST_ValidationFailure
s as appropriate, without having to write a lot of additional code to catch and deal with those. - If neither of the above custom classes have been used,
handle_api_method_exception()
will issue a response to the front end with a generic 'An unknown error has occurred, please try again or reload the screen.' message to be displayed to the user.
Implications
- Cleaner and clearer error and validation handling in API code :)
- Top-level API methods can be simplified along the lines of the example above:
- Minimal processing happening in the method.
- Method is mainly responsible for initiating the work and issuing a 'success' response when it's done.
- Any errors can be detected in lower level code and thrown up to the single catch-all exception handler.
Setup
None
How to test
- Code review.
- Can be tested in AFES project (at commit c07dc4f14b70936fe6101c7e6866a504585450df in the
release/donation_portal_phase_2
branch) by clicking the [Donated Before?] button on the donation form while not logged in, filling it out, and submitting.- Fatality report behaviour can be tested by by hard-coding a failure in
_donated_before()
in fmsync.php, e.g. copying the finalthrow
from the bottom of the method to the top.- Change the two
null
parameters to strings in order to also generate an error notification email.
- Change the two
- Validation behaviour can be tested by hard-coding a failure in
_validate_donated_before_form()
infmsync.php
, e.g. by adding|numeric
to the rules for one of the name fields.
- Fatality report behaviour can be tested by by hard-coding a failure in