Skip to main content

Error and Exception Handling

Most applications evolve over time with new functionalities being added or modified as business requirements change.

The AVRO framework allows applications to run in two modes: production and development.

  • Production Mode: When an error occurs, execution is redirected to an error page that displays the error message defined in the application configuration file. This message is displayed in the current application language.
  • Development Mode: Execution is redirected to a detailed error page, where you can see all available information about the error type, message, file, and line.

Error handling can be configured by editing the application configuration file and specifying the appropriate level of error reporting: errors, warnings, or notices.

There are also configuration options that let you define the level of detail you want for error reporting.

How Can You Report Errors You Detected?​

At some point in your code, you may encounter a situation where there is nothing else to do but report an error and abort execution.

The framework intercepts and handles error events triggered in several different ways:

trigger_error('error message', E_USER_ERROR, __FILE__, __LINE__);

This is the PHP standard error triggering function.

AVRO provides two methods that behave similarly:

$this->app->error(E_USER_ERROR, 'error message', [file], [line]);
tk_e::error(E_USER_ERROR, 'error message', [file], [line]);

These methods trigger an error when called, which will be handled by the framework.

What About Error 404?​

In Web mode, your application may decide to generate a "404 - Page not found" error.

This can be done easily as shown below:

$this->app->error_404($_optional_message);

The effect of this call is to redirect the application to the 404 error page. This 404-page may be a page that you provide or the default page defined in your web server configuration.

How Can You Log Errors?​

Reporting an error and aborting execution is unavoidable in certain circumstances because there is no sensible action that can be taken to recover from that situation.

However, not all errors should be handled in such a drastic way. You may want to log a message to keep a trace that some unexpected event has occurred, but that execution could continue nevertheless.

AVRO provides a log class library which makes it straightforward to log not only errors but also any message, including variable dumps or execution trace information, which is helpful for debugging during the development stage.

Every addon inherits a log object when its instance is created. It will write to a file whose name is the name of the addon prefixed with 'addon_' and with the .log extension.

To use it, call its write method and pass the string you want to log as a parameter.

Example:

$this->log->write('some message');

This call will log the string 'some message' together with a timestamp in the addon's log file.

To dump the value of an array for debugging purposes:

$this->log->write('Dump of my_array: ' . var_export($my_array, true));

You may want to log certain types of events in different log files. To do this, create other instances of the log object by calling the instance method of the log library:

$my_log = $this->lib->log->instance('log/file/path', [max_size_in_bytes], [log/files/path]);
  • max_size_in_bytes: Used to trigger a log change mechanism. When the log file size reaches this value, the class will automatically compress (gzip) it and continue writing in a new empty log file.

The log library includes other functions like compress, uncompress, files_list, files_clean, and more to make the management of log files fast and easy.

Log files are created in the /application/log/ directory.

Error Handler Configuration​

The /application/config/application.ini file contains a section that you can edit to set the error handling to work the way you want.

You can turn an option on by assigning 1 to the corresponding parameter and off by assigning 0.

The log_* options are used to turn automatic logging of errors of a given level on or off.

The show_* options are used to turn on-screen display of errors of a given level on or off.

Note: In production mode, real error messages are not shown. Instead, the generic messages you configured are displayed in the proper language.

Example configuration:

[ERROR_HANDLING]
; What events/errors to be logged
log_notices=1
log_warnings=1
log_errors=1
log_unknown_errors=1
log_errors_404=1

; What events/errors to be displayed
; NOTE: In production mode, real error messages are not shown
show_notices=1
show_warnings=1
show_errors=1
show_unknown_errors=1

; log file extension
log_file_extension=log