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. Following are the available exception classes.

/**
* Sahana Sql Exception Class. This will be called with the following params
*
* @param $dbms		the RDBMS you are connecting to
* @param $fn		the name of the calling function (in uppercase) default is EXECUTE
* @param $errno		the native error number from the database
* @param $errmsg	the native error msg from the database
* @param $p1		$fn specific parameter - see below
* @param $P2		$fn specific parameter - see below
* Developer can override above parameters if necessary but these values are implicitly assign using conf[] variables 
*/
class SahanaSQLException extends Exception{
 
}
 
For more information please refer to the ../inc/lib_exception.inc

NOTE : Transaction support is not implemented in the exception library due to unavailability of the mysql transaction support. Please implement it when they support transactions in mysql drivers.

/** SahanaIOException is the general class of exceptions produced by failed or interrupted I/O operations 
* @param $msg			the message about the exception
* @param $mod			the module name
* @param $act			the module action name 
* @param $errno			the error number of the exception
*/
class SahanaIOException extends Exception{
 
}
 
 
/** SahanaFileNotFoundException Signals that an attempt to open the file denoted by a specified pathname has failed.
* @param $msg			the message about the exception
* @param $file_name		the file name
* @param $errno			the error number of the exception
*/
class SahanaFileNotFoundException extends Exception{
 
}
 
 
/** SahanaFilePermissionDeniedException Signals that an attempt to open the file denoted by a specified pathname has failed due to permission.
* @param $msg			the message about the exception
* @param $file_path		the path of the file or file name
* @param $errno			the error number of the exception
*/
class SahanaFilePermissionDeniedException extends Exception{
 
}
 
/**
*NOTE : IOException class which you are looking for is not written in above code then please write your own IOException class
*within above code snippet. When you are writing your own class please extends Exception class otherwise your are not able to throw an exception 
*without a class object.
*/
 
For more information please refer to the ../inc/lib_exception.inc

/** SahanaAclNotFoundException Signals that an attempt to handle ACL and when it's failed.
* @param $msg			the message about the exception
* @param $mod			the module name
* @param $act			the module action name
* @param $errno			the error number of the exception
*/
class SahanaAclNotFoundException extends Exception{
 
}
 
NOTE : Please customize this class to add more functionalties. 
 
For more information please refer to the ../inc/lib_exception.inc

/**
* The generic exception class where other custom exceptions can inherit from. 
* @param $msg			the user friendly message about the exception
* @param $mod			the module name
* @param $act			the module action name
* @param $errno			the error number of the exception
*/
/*This class throw SahanaUncaughtException exception*/
class SahanaException extends Exception {
 
}
 
 
NOTE : Please customize this class to when neccesary 
 
For more information please refer to the ../inc/lib_exception.inc

Sets the default exception handler if an exception is not caught within a try/catch block. Execution will stop after the exception_handler is called.

/**This function will execute when module developer throw new exception without a try/catch block
* @param $exception_msg		the message about the exception.
* @param $display_error		You can call diplay_errors() function from this parameter.
*/
 
function shn_sahana_exception_handler($exception_msg,$display_error=false){
 
}

For more information please refer to : http://www.php.net/set-exception-handler

Below mentioned code snippet show how to write your own exception class

class Sahana[your-exception-name-comes-here] extends Exception {
 
function __construct($msg,parameter1,parameter2,....,$errno=0){
 
     //parameter declaration is come here
 
     if (!is_numeric($errno)) $errno = -1;
	parent::__construct($msg,$errno); //this line is required.
 
     }
 
}

For more information see the references.

Following are some examples of the use of exception class.

global $global;
include_once $global['approot']."/inc/lib_exception.inc";
 
if($file_n == null)
    		$file_name = "../res/locale/$locale/LC_MESSAGES/sahana.po";
	else
		$file_name = $file_n;
 
	try{
		if(!file_exists($file_name)){
			throw new SahanaFileNotFoundException("Please create the file first",$file_name);
		}else if(!is_readable($file_name)){
                        throw new SahanaFilePermissionDeniedException("Please give permission to file",$file_name);
                }else{
                        //rest of the code to handle the file.
                }
 
           }catch(SahanaFileNotFoundException $e){
			add_error($e->getMessage()); /**if file not found then display error and exit */
			diplay_errors();
                        exit;
	   }catch(SahanaFilePermissionDeniedException $e){
			add_error($e->getMessage()); /**if file doen't have write permission then exit from this function any excute rest of the code*/
			return;
	   }catch(Exception $e){
                        add_error($e->getMessage()); /**Throw generic exception and execute the rest of the code.*/			
           }

global $global;
include_once $global['approot']."/inc/lib_exception.inc";
 
try{
 
        $query = "INSERT INTO pgroup1(g_uuid,opt_group_type) VALUES ('{$groupid}','{$_SESSION['dvr']['group']['typ_of_grp']}')";
	if ( $global['db']->Execute($query)=== false)
   	     throw new SahanaSQLException();
        else
             //rest of the code
}catch(SahanaSQLException $e){
	add_error($e->getMessage());
	diplay_errors();
	exit;
}catch(Exception $e){
	add_error($e->getMessage());	
        return;
}

The use of default exception handler. In this scenario developer able to pass user friendly message to handler and try/catch block is not reuired but this way of exception handling is not recomended but accepted.

global $global;
include_once $global['approot']."/inc/lib_exception.inc";
 
if(!is_readable($file_name)
    throw new Exception("File cannot be read, please give permission");
else
    //reset of the code

http://www.php.net/exceptions http://www.php.net/set-exception-handler

NOTE : Previous documentation is below mentioned

Previous Exception Handling Documentation - english