Logging / Exception Handling

Exception Handling

The Sahana System wide Exception Handling works according to a handle and report scenario. The module developer has to handle the exceptions accordingly and has the choice of reporting about the exception to the framework through report_exception().

All exception reporting api functions are available in inc/lib_exception.inc.

The lib_exception.inc has the following api functions.

/**
 * Report an exception to the framework.
 *
 * @param SahanaException $exception The target exception.
 * @param array $extra_opts Any extra options.
 */
function report_exception($exception,array $extra_opts=null)

Further it provides a SahanaException class, which is a generic exception class, where custom exceptions can inherit from.

/**
 * The generic exception class where other custom exceptions can inherit from.
 *
 */
class SahanaException{
 
	/**
	 * The user friendly message for this exception.
	 *
	 * @var String The user friendly message.
	 */
	private $message;
	/**
	 * The module short code of the module which generated this exception.
	 *
	 * @var String The module short code of the module which the exception occured.
	 */
	private $module;
	/**
	 * The action which generated this exception.
	 *
	 * @var String The action
	 */
	private $action;
	/**
	 * The result of this exception, either of REPORT_AND_ABORT or REPORT_AND_CONTINUE.
	 *
	 * @var String The result
	 */
	private $result;
 
	/**
	 * Return the user friendly message, for this exception. All messages should be localized.
	 *
	 * @return String Localized user friendly message.
	 */
	function getMessage(){
		return $this->message;
	}
 
	/**
	 * Return the module short code of the module which generated this exception.
	 *
	 * @return String The module short code of the module which generated this exception.
	 */
	function getModule(){
		return $this->module;
	}
 
	/**
	 * Return the action which generated this exception.
	 *
	 * @return String The action.
	 */
	function getAction(){
		return $this->action;
	}
 
	/**
	 * Return the result of this exception. There can be only two results.
	 * REPORT_AND_ABORT which will not display any page content but just an error message to the user.
	 * REPORT_AND_CONTINUE which will display a warning and the page content.
	 *
	 * @return String The result.
	 */
	function getResult(){
		return $this->result;
	}
 
	/**
	 * The constructor for SahanaException.
	 *
	 * @param String $msg The localized user friendly message for this exception.
	 * @param String $mod The module which generated the exception. Value is obtained from $global['module'] if not provided.
	 * @param String $act The action which generated the exception. Value is obtained form $global['action'] if not provided.
	 * @param String $result The result of the exception, should be one of REPORT_AND_CONTINUE or REPORT_AND_ABORT.
	 * @param array $extra_opts Any extra options for future customizations.
	 * @return SahanaException
	 */
	function SahanaException($msg,$mod = null,$act = null,$result = null,array $extra_opts = null){
		global $global;
		$this->message = $msg;
		$this->module = ($mod!=null)?$mod:$global['module'];
		$this->action = ($act!=null)?$act:$global['action'];
		$this->result = ($result!=null)?$result:REPORT_AND_ABORT;
	}
}

Usage

The usage of the exception reporting functions are as follows.

// construct or catch an exception accordingly
$exception = <the caught or constructed exception>
// report the exception to the framework.
report_exception($exception);