Documentation
Working with application
Error and Exception handling
Most applications are evolving over time with new functionality being added or modified as the business requirements change.
The toKernel framework allows applications to be run in two modes, production and development.
When an error occurs in production mode, 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.
However, in development mode, execution will be 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 some situation where there is nothing else to do but report an error and abort execution.
The framework is intercept and handle in a similar way error events triggered in several different ways.
trigger_error('error message', E_USER_ERROR, __FILE__, __LINE__);
This is the PHP standard error triggering function.
$this->app->error(E_USER_ERROR, 'error message', [file], [line]);
tk_e::error(E_USER_ERROR, 'error message', [file], [line]);
These two methods are provided by toKernel and behave similarly. They will trigger an error when they are 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 very easily as shown below:
$this->app->error_404($_optional_message);
the effect of this call will be 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 and you may want just to log a message to keep a trace that some unexpected event has occured but that execution could continue nevertheless.
toKernel provides a log class library which makes it very easy to log not only errors but also any message including variables dump, or execution trace information which makes it very helpful for debugging during the development stage.
Every addon inherits a log object when it's 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, all that is required is a call to its write method and pass the string you want to log as parameter.
For 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 some array for debuggin purposes, you can do:
$this->log->write('Dump of my_array: ' . var_export(my_array, true));
You may want to log certain type of events in different log files, so you need to create other instances of the log object. This can be done 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]);
The max_size_in_bytes is used to trigger a log change mechanism. When the log file size reaches that 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. See the log library documentation.
Log files are created in the /application/log/ directory.
Error handler configuration
The /application/config/tokernel.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 user to turn on screen display of error of a given level on or off.
This is only taken in consideration while running in development mode. In production mode, errors are logged in the appropriate log file according to the options settings but are never shown on the screen. Instead the generic messages you configured are displayed in the proprer language.
[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
show_errors_404=1
; log file extension
log_file_extension=log
See also: log class library