Error Handling

Overview

Errors in Yukon are handled by throwing exceptions that may be caught by your application. Exceptions are identified by code constants, allowing your application to pinpoint the specific exception and act accordingly.

Consider the following example, illustrating the recommended pattern for error handling. We'll start by preparing a configuration object for connecting to the database host, but we will intentionally leave the host member blank.

// Establish connection configuration object.
$yukon_connect_config = new \dc\yukon\ConnectConfig();

// Add connection arguments.
$yukon_connect_config->set_host('');
$yukon_connect_config->set_name('some name');
$yukon_connect_config->set_user('john doe user');
$yukon_connect_config->set_password('password');

Now we will enclose our open connection attempt in a try...catch block.

// Open connection with configuration arguments.
try
{
	$yukon_connection 	= new \dc\yukon\Connect($yukon_connect_config);
}
catch(\dc\yukon\Exception $exception)
{	
	switch($exception->getCode())
	{
		// Bad or invalid host.
		case \dc\yukon\EXCEPTION_CODE::CONNECT_OPEN_HOST:

			die($exception->getMessage());
			break;

		// Driver returned a failure response trying to connect.
		case \dc\yukon\EXCEPTION_CODE::CONNECT_OPEN_FAIL:

			die($exception->getMessage());
			break;
	}
}

Without a target, any connection attempt will fail. In this case Yukon will detect the missing host argument and throw an exception code CONNECT_OPEN_HOST. You can then decide how to catch and handle the exception gracefully in your application.

Configuration

Exemptions

Exemption Overview

Yukon allows you to define lists of exemptions at run-time, giving you full granular control over which exceptions are passed on to your application vs. being handled by Yukon. Each level of error handling has its own exemption list, definable in config.class.php.

1. Error. During operation, all driver requests, user actions and required arguments are verified for errors. By default, the following exemptions are defined.
   • Cursor type change.
   • Database context change.
   • Language setting change.
2. Exception. Any errors or requirement violations will result in a thrown exception code. No default exemptions are defined.
3. Catch. It is highly recommended you catch thrown exceptions within your application and handle them accordingly. By default, Yukon allows all exemptions to pass through.

Configuring Exemptions

Exemptions lists are part of the Error Configuration object. All exemption lists accept a doubly linked list object of exempt codes. Access exemption lists with the following methods.

set_exempt_codes_driver(SplDoublyLinkedList $value);	// Set exemption list for detecting driver and user errors.
set_exempt_codes_throw(SplDoublyLinkedList $value);	// Set exemption list when throwing exceptions. 
set_exempt_codes_catch(SplDoublyLinkedList $value);	// Set exemption list for catching thrown exceptions.
get_exempt_codes_driver();				// Current list for detecting driver and user errors.
get_exempt_codes_throw();				// Current list when throwing exceptions.
get_exempt_codes_catch();				// Current list or catching thrown exceptions.

Create Exemption List

1. Create a list object (See here if you are unfamiliar with the doubly linked list data structure).

   // New list for error codes.
   $codes = new SplDoublyLinkedList();

2. Push error codes you would like to ignore.

   // Error codes to ignore.
   $codes->push(0);	// Cursor type changed.
   $codes->push(5701);	// Changed database context.
   $codes->push(5703);	// Changed language setting.

3. Pass the list object into error config.

   $error_config->set_exempt_codes_driver($codes);

Constants

Error code and (optional) message constants are located in config.php.