Intro

(INSTRUCTIONS LAST UPDATED FOR V3.0)

It's often necessary in the course of development to have a means to find and catch error conditions so that they can be dealt with cleanly and safely. A Bright CMS offers some tools out of the box to help with this, so we'll go through these one by one.

Debugging

Debugging sometimes requires going line by line, outputting current variable states to the screen to determine what is happening. A Bright CMS makes this a little easier by providing a Debug class with static methods so that they may be called anywhere.

First, we must make sure that debug mode is set to true, which we can find by checking settings.php in application/config. By default, debug mode should be on, but it is recommended to turn this off for production environments so that any code accidently left over using these methods, will not be output.

Our Debug class has the following public static methods:

printArray($value, $is_exit = true)
varDump($value, $is_exit = true)
stackTrace($is_exit = true)

The is_exit argument allows us to determine if program execution will be halted immediately after the output from our debug method. By default, this is set to true, since it is often useful to stop the program to see our output cleanly.

printArray and varDump both take a mixed type variable as the first argument, the former outputting the data cleanly with print_r and the later with var_dump.

stackTrace outputs the stack trace with PHP's debug_backtrace().

Exceptions

Exceptions are best used when there are expected, exceptional circumstances in the code where a specific error message is useful for debugging, preventing a user action, or can be handled in some way.

A Bright CMS has a MyException class which extends functionality from PHP's built in Exception class. The MyException class helps us with displaying and logging errors, and since it has some dependencies, and we want forwards compatibility with future changes, we call it with our ApplicationFactory class like so:

throw ApplicationFactory::makeException($exception_name, $exception_error_code);

Some base classes in system/core, such as our Json and Xml classes, will have some exceptions built in. Error codes are listed at the top of the class as constants like so:

/**
 * Error codes for Json
 */
const JSON_LAST_ERROR_DECODE = 1001;
const JSON_LAST_ERROR_ENCODE = 1002;
const COULD_NOT_CONVERT_TO_BOOLEAN = 1003;
const FILE_DOES_NOT_EXIST = 1004;

The error codes are then called into exceptions within the class using the self keyword like so:

throw ApplicationFactory::makeException('Json Exception', self::FILE_DOES_NOT_EXIST);

Now, if exceptions are outputted to the user this way, users will have a specific means of identifying it: through the numbered code. However, a user will not know what this code means, hence keeping sensitive system information away from them.

But as the program author, you will be able to identify the meaning of the code, as it is tied to the constant name. If every exception thrown has a unique name, then it will also have a unique place in the code, making it even easier to identify where the problem originated.

Since A Bright CMS is open source, all exception codes are the same by default, and anyone can look up what they mean simply by viewing the source for themselves on github. Therefore, it is recommended that the numbered codes be changed in production environments, obfuscating what codes pertain to what exceptions.

If logging mode is set to true in settings.php, as it is by default, then our MyExceptions class will also log any exceptions encountered that are caught using the caughtException() method, as well as any uncaught exceptions. This way, you can find out about exceptions by looking at logs in the application/logs folder, learning about them even if the users did not report them to you.

Errors

Errors are the built in PHP errors that are often unrecoverable and halt program execution. It's always best to be notified if any of these creep into your program. It's also important to hide these from users, as PHP will dump stack traces with specific class/method names and line numbers: very danergous information to release into the wild.

In development environments, it's best to see any of these errors immediately, so that they can be resolved. Therefore, we production mode is set to false, all errors and warnings are reported.

If production mode is set to true in settings.php, A Bright CMS hides all error reporting for users, but has an ErrorHandler class that automatically manages such errors for us so that we can still find out about them and deal with them.

The class detects if PHP has encountered an error with error_get_last(), and if so, it logs the error, emails the error to the default email address set in settings.php, and displays a custom error page contained in application/views/_template.

Any such errors will then be emailed so that you can be notified without having to check the logs (though the logs will keep a record of these as well).

It is also recommended that you customize the error page template to make it friendlier to users, perhaps providing them with contact information or alternative courses of action.

Conclusion

A Bright CMS contains some basic functionality to help you with debugging, exceptions, and errors but no sound program should rely on the means provided by A Bright CMS alone.

It's always good to use coding practices that make errors easier to avoid and catch before they become real problems. Writing unit tests can help with this also, but that's a topic best left for another time. :)

Good luck and happy coding!