---

Raising errors

If at some point in your code an error occured, you might want to signal this to the caller of the method that the error occured in.

This is where patError comes into play. patError helps you encapsulating all available information in an error object that will be processed by the caller who is responsible for the error handling. A patError object contains the following information, which you need to specify:

• error level
• unique error code
• error message
• some optional information which helps locating the error

In addition to this information, it will give you access to the following data, which is auto-generated:

• file, in which the error occurred
• line number, in which the error occured
• backtrace

How do I create an error object

When creating error objects, you may use various static methods provided by the patErrorManager class. Let's say, you are implementing a simple class that opens reads files and you want to use patError for error-management:

define('ERROR_FILE_NOT_FOUND', 1);
define('ERROR_FILE_NOT_READABLE', 2);

define('NOTICE_FILE_EMPTY', 101);

class FileReader {
    var $filename = null;
    var $fp = null;

    function FileReader($filename) {
        $this->filename = $filename;
    }

    function open() {
        if (!file_exists($this->filename)) {
            return patErrorManager::raiseError(ERROR_FILE_NOT_FOUND, 'The file does not exist.');
        }
        if (!is_readable($this->filename)) {
            return patErrorManager::raiseError(ERROR_FILE_NOT_READABLE, 'The file is not readable.');
        }
        if (filesize($this->filename) === 0) {
            patErrorManager::raiseNotice(NOTICE_FILE_EMPTY, 'The file is empty.');
        }
        $this->fp = fopen($this->filename, 'r');
        return true;
    }
}

At first, we are defining three new constants:

• ERROR_FILE_NOT_FOUND and ERROR_FILE_NOT_READABLE contain codes for serious errors
• NOTICE_FILE_EMPTY contains a code for a notice

In the open() method, we execute various checks, to determine, whether the supplied file exists and can be opened. If any of these checks fail, we are using the patErrorManager::raiseError() method to construct a new error object by passing the following arguments:

1. Error code
2. Error message
3. Additional error information (optional)

If the file exists and is readable, we can be sure, that we can open the file and continue with our work. However, we want to be informed, whether the file is empty and thus include a third check, which calculates the filesize. If the file is empty, we use a different method of patErrorManager to construct a notice. but we do not return the object created by the method, as this is no condition which should lead to a break in our method execution. Instead we open the file and store the resource in an object property.

Now we have created our first patError objects using patErrorManager. This class provides the following methods for raising errors:

• raiseError($code, $msg, $info = null)
• raiseWarning($code, $msg, $info = null)
• raiseNotice($code, $msg, $info = null)
• raise($level, $code, $msg, $info = null)

The first three methods are just shortcuts to calling raise() and passing information about the error level. Using raiseError(), raiseWarning() or raiseNotice() instead makes your code more readable. patErrorManager also allows you to define your own error levels.

Now, that we have created error objects, we will continue by learning how to handle them.