Tutorials: Error Handling

├─ Setting If Errors Should Be Displayed
├─ Getting Exception Information
├─ Setting Error Reporters
└─ Writing New Error Reporters

Setting If Errors Should Be Displayed

By default, when your site is created, framework takes decision in stderr.xml file to display errors via <display_errors> tag:

<display_errors>
    <local>1</local>
</display_errors>

For live DEVELOPMENT ENVIRONMENT, however, you would not like to display errors to outside world, so change above to:

<display_errors>
    <local>1</local>
    <live>0</live>
</display_errors>

Getting Exception Information

Framework collects via STDERR MVC API information about uncaught exception/error handled and matching <route> route into a Lucinda\STDERR\Request object. Only this method is relevant for developers:

getException(): gets uncaught exception handled. Usage example in controllers:
$errorMessage = $this->request->getException()->getMessage();

Setting Error Reporters

In order to log errors automatically, you first need to open stderr.xml and create a <reporter> tag (which will hold your reporter settings), child of DEVELOPMENT ENVIRONMENT tag, child of <reporters> tag. Example:

<reporters>
    <local>
        <reporter class="Lucinda\Project\ErrorReporters\File" path="C:\xampp\htdocs\errors" format="%d %v %u %e %f %l %m"/>
        ...
    </local>
</reporters>

This configures reporting into an C:\xampp\htdocs\error.log file for local DEVELOPMENT ENVIRONMENT. Each class attribute points to a class name in src/ErrorReporters that must extend Lucinda\STDERR\Reporter. Framework comes with two implementations by default:

Lucinda\Project\ErrorReporters\File: automatically reports errors to rotating files
Lucinda\Project\ErrorReporters\SysLog: automatically reports errors to syslog

Formatting Log Line

If you are using a Lucinda\Logging\Logger binding as the two above, log lines can be formatted via format attribute above on a combination of following placeholders:

%d: current date using Y-m-d H:i:s format.
%v: syslog priority level constant value matching exception thrown
%e: name of thrown exception class
%f: absolute location of file that has thrown a Throwable/Exception
%l: line in file above at which Throwable/Exception was thrown
%e: class name of Throwable/Exception thrown
%m: value of Throwable/Exception message
%u: value of URL that came along with request ($_SERVER["REQUEST_URI"])
%a: value of USER AGENT header that came along with request ($_SERVER["HTTP_USER_AGENT"])
%i: value of IP request came from ($_SERVER["REMOTE_ADDR"])

Writing New Error Reporters

Rarely, developers may need a solution for error reporting other than the one that comes with framework already, defined by Setting Error Reporters section. To do so, they must first register a new <reporter> tag @ stderr.xml. Example:

<reporters>
    <local>
        ...
        <reporter class="Lucinda\Project\ErrorReporters\SQLWrapper"/>
    </local>
    ...
</reporters>

Above is set to report errors in table errors via class Lucinda\Project\ErrorReporters\SQLWrapper that must extend Lucinda\Framework\AbstractReporter and be located in src/ErrorReporters folder. Example:

namespace Lucinda\Project\ErrorReporters;

class SQLWrapper extends \Lucinda\Framework\AbstractReporter
{
    public function getLogger(): \Lucinda\Logging\Logger
    {
        return new SQLReporter();
    }
}

Now that a XML binder for reporter is made, you will need to create (in same folder) the Lucinda\Logging\Logger driver:

namespace Lucinda\Project\ErrorReporters;

use Lucinda\Project\DAO\Entities\Log;
use Lucinda\Project\DAO\Logs;

class SQLReporter extends \Lucinda\Logging\Logger
{    
    protected function log($throwable, int $level): void;
    {        
        try {
            // define entity
            $log = new Log();
            $log->message = $throwable->getMessage();
            $log->file = $throwable->getFile();
            $log->line = $throwable->getLine();
            
            // persist entity to DB via DAO
            $logs = new Logs();
            $logs->write($log);            
        } catch(\Exception $e) {}
    }
}

Now you need to create src/DAO/Entities/Log.php struct-style encapsulating log blueprints class with following body:

namespace Lucinda\Project\DAO\Entities\Log;

class Log
{
    public $message;
    public $file;
    public $line;
}

And DAO src/DAO/Logs.php file encapsulating log operations with following body:

namespace Lucinda\Project\Logs;

use Lucinda\Project\DAO\Entities\Log;

class Logs
{
    protected function write(Log $log): void;
    {    
        \SQL("INSERT INTO errors (message, file, line) VALUES (:message, :file, :line)", [
            ":message"=>$log->message, 
            ":file"=>$log->file, 
            ":line"=>$log->line
        ]);
    }
}

assuming following MySQL table structure:

CREATE TABLE errors (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
    message TEXT NOT NULL,
    file VARCHAR(255) NOT NULL,
    line VARCHAR(255) NOT NULL,
    date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY(id)
)

□ ×