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.
• 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 to DF_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 throw DF_Rest_FatalityReports and DF_REST_ValidationFailures 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 final throw 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.
  • Validation behaviour can be tested by hard-coding a failure in _validate_donated_before_form() in fmsync.php, e.g. by adding |numeric to the rules for one of the name fields.