Tutorials: Logging

├─ Setting Loggers
├─ Logging Messages
└─ Writing New Loggers

Setting Loggers

In order to be able to log messages later on, you need to open bootstrap index.php file and add this event listener to Lucinda\STDOUT\FrontController object:

$object->addEventListener(Lucinda\STDOUT\EventType::APPLICATION, Lucinda\Project\EventListeners\Logging::class);

and / or to Lucinda\ConsoleSTDOUT\FrontController object:

$object->addEventListener(Lucinda\ConsoleSTDOUT\EventType::APPLICATION, Lucinda\Project\EventListeners\Console\Logging::class);

then create a <logger> tag (which will hold your logger settings), child of DEVELOPMENT ENVIRONMENT tag (because logging policies may be different on another environment), child of <loggers> tag. Example:

<loggers>
    <local>
        <logger class="Lucinda\Project\Loggers\File" path="C:\xampp\htdocs\messages" format="%d %f %l %m"/>
        ...
    </local>
</loggers>

This configures logging into a C:\xampp\htdocs\messages.log file for local DEVELOPMENT ENVIRONMENT. Each class attribute points to a class name in src/Loggers that must extend Lucinda\Logging\AbstractLoggerWrapper. Framework comes with two by default:

Lucinda\Project\Loggers\File: logs message into rotating files
Lucinda\Project\Loggers\SysLog: logs message into syslog

Formatting Log Line

If you're using Lucinda\Logging\Logger implementation above, log line can be formatted via format attribute based on a combination of following placeholders:

%d: current date using Y-m-d H:i:s format.
%v: syslog priority level constant value matching to Logger method called.
%f: absolute location of file that called logging
%l: line in file above at which logging was called
%m: value of log 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"])

Logging Messages

After you have completed Setting Loggers section described above, you are now able to log messages. To log a message in a controller or a subsequent event listener use:

$this->attributes->getLogger()

To return a Lucinda\Logging\MultiLogger instance that automatically distributes same message to all loggers registered on that DEVELOPMENT_ENVIRONMENT. Example:

$this->attributes->getLogger()->info("hello");

Assuming XML is same as in previous section, a new line is appended in file C:\xampp\htdocs\messages.log. Example:

2025-11-04 21:07:27 src/Controllers/TestController 10 hello

Writing New Loggers

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

<loggers>
    <local>
        ...
        <logger class="Lucinda\Project\Loggers\SQLWrapper"/>
    </local>
    ...
</loggers>

Above is set to log messages in table logs via class Lucinda\Project\Loggers\SQLWrapper that must extend Lucinda\Logging\AbstractLoggerWrapper and be located in src/Loggers folder. Example:

namespace Lucinda\Project\Loggers;

class SQLWrapper extends \Lucinda\Logging\AbstractLoggerWrapper
{
    protected function setLogger(\SimpleXMLElement $xml): \Lucinda\Logging\Logger
    {
        return new SQLLogger();
    }
}

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

namespace Lucinda\Project\Loggers;

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

class SQLLogger extends \Lucinda\Logging\Logger
{
    protected function log($message, int $level): void;
    {        
        $info = debug_backtrace()[1];
        try {
            // define entity
            $log = new Log();
            $log->message = $message;
            $log->file = $info["file"];
            $log->line = $info["line"];
            
            // persist entity to DB via DAO
            $logs = new Logs($tableName);
            $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 logs (message, file, line) VALUES (:message, :file, :line)", [
            ":message"=>$log->message, 
            ":file"=>$log->file, 
            ":line"=>$log->line
        ]);
    }
}

assuming following MySQL table structure:

CREATE TABLE logs (
    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)
)

□ ×