Skip to content

Logging

What is this?

ZubZet provides a built-in logging system powered by Monolog. It allows you to record application events, errors, and diagnostic information either to a database table or to a stream (file or stderr). The framework automatically logs certain system events such as logins, page views, and REST errors. Which of them are stored depends on logger_level.

Loggers are created lazily on first use and cached for the lifetime of the request, so there is no overhead for channels that are never written to.

Disabling Logging

Logging is enabled by default. To disable it, set the following in z_config/z_settings.ini:

logger_enabled = false

When disabled, all logger() calls still work but write to a NullHandler — log messages are silently discarded without any errors.

Configuration

All logger settings are configured in z_config/z_settings.ini.

Key Type Default Description
logger_enabled boolean true Enables or disables the logging system entirely
logger_type string database The logger backend, database or stream (case-sensitive); any other value throws an InvalidArgumentException
logger_level string notice Minimum log level to record: a name (case-insensitive) or number, see below; an unknown name throws an InvalidArgumentException
logger_stream_url string php://stderr Stream target — only used when logger_type = stream
logger_slow_request_ms number 1000 Requests at least this slow (>=) are logged as SLOW_REQUEST at shutdown (not after an uncaught exception; console commands count too); a negative or non-numeric value disables it
logger_slow_query_ms number 300 exec() queries (so execQuery(), not executeMultiQuery()) taking at least this many milliseconds (>=, so 0 logs every query; measured from prepare to execute, retries included, result fetch excluded) are logged as SLOW_QUERY (without disturbing getInsertId() or the current result); an INI file cannot disable it, so use a high threshold

Log Levels

Log levels follow the Monolog/PSR-3 standard. Set logger_level to a level name — only records at or above that level are stored.

logger_level value Description
debug Detailed diagnostic information
info Normal operational events
notice Significant but expected events
warning Exceptional but non-critical events
error Runtime errors
critical Critical conditions
alert Action must be taken immediately
emergency System is unusable

The framework logs its own events on the zubzet channel (Logger::ZUBZET) at different levels. The event names are the constants of ZubZet\Framework\Logger\LogEventType and become the record message. With the default notice, the info events are dropped by the handler and not stored; set logger_level = info to record them.

Level Framework events
info RENDER (every rendered view, mail renders included; context location, view, viewName, layout, layoutName), USER_LOGGED_IN (userId), USER_LOGGED_IN_ANOTHER (userId, userId_exec), USER_LOGGED_OUT (userId), USER_CREATED (userId, email; written by z_userModel::add(), so also by signup, User::add() and the admin add-user page), ACCOUNT_UPDATED (userId; admin edit-user adds the old email, two-factor changes a reason), PASSWORD_RESET_REQUESTED (userId; only when the email matched an account), PASSWORD_RESET (userId, reason)
warning SLOW_REQUEST (duration_ms, uri), SLOW_QUERY (duration_ms, query without bound values), REST_ERROR (code, message), ACCOUNT_LOGIN_RATE_LIMITED (userId)
error EXCEPTION (class, message, file, line, trace)

PHP errors are logged as ERROR (error), PARSE (critical), WARNING (warning), DEPRECATION/NOTICE (notice) or STRICT (debug), depending on their severity (any other severity is logged as ERROR with level warning), with the context message, file and line. Failed password attempts, verification success, logouts of anonymous requests and admin actions (roles, permissions, database browsing) write no event, and sendEmail() failures are echoed instead of logged. @-suppressed errors and fatal errors are not logged.

Writing Log Entries

Use the global logger() helper function anywhere in your application.

// Log to the app channel
logger()->info("User submitted a contact form", ["email" => $email]);

// Log to a named channel
logger("payments")->warning("Payment gateway timeout", ["orderId" => $id]);

logger() without arguments defaults to the "app" channel (Logger::APP). Any string can be passed to create a named channel — each channel is cached after the first call.

Available Methods

logger()->debug("message", $context);
logger()->info("message", $context);
logger()->notice("message", $context);
logger()->warning("message", $context);
logger()->error("message", $context);
logger()->critical("message", $context);
logger()->alert("message", $context);
logger()->emergency("message", $context);
logger()->log($level, "message", $context);

The second parameter $context is an optional associative array with additional data to attach to the log record. PSR-3 {placeholder} interpolation in the message is not active.

Keys that should accompany every later record of a channel go into extra instead, via logger()->contextAdd([...]), contextMergeFrom($name = "app") (the source channel wins on shared keys; an empty name or a channel that was never created throws), contextInspect(fn($context) => ...) (the return value replaces the context) and contextClear(). All of them return the logger and can be chained, and a key named traceId, file or line overrides the built-in value.

Every record carries a 32-character hex extra.traceId, generated on first use and shared by the whole request. The framework reads no incoming trace header, so propagate one with Logger::setTraceId($id) (not validated, only later records carry it); Logger::getTraceId() returns it.

Registering a Custom Logger

If you need full control over a logger — custom handlers, formatters, or processors — you can build a ZubZet\Framework\Logger\Logger instance (it extends the Monolog Logger) manually and register it under a channel name using LoggerFactory::register(). Once registered, it is returned by logger() like any other channel, but it gets none of the logger_* handler and processor setup (no traceId or call-site extra unless you add a processor).

use Monolog\Handler\RotatingFileHandler;
use ZubZet\Framework\Logger\Logger;
use ZubZet\Framework\Logger\LoggerFactory;

$customLogger = new Logger("audit");
$customLogger->pushHandler(new RotatingFileHandler("/var/log/audit.log", 30));

LoggerFactory::register("audit", $customLogger);
// Anywhere in your application
logger("audit")->info("User exported data", ["userId" => $id]);

If a logger with that name was already created by the framework, register() overwrites it in the cache. logger() builds channels from the logger_* settings via LoggerFactory::getOrCreateLogger(), while LoggerFactory::getLogger($name) only returns a cached channel or null.

The parameter is typed Logger|LoggerInterface, but register() and logger() are declared to return the ZubZet Logger. A plain Monolog Logger or any other PSR-3 logger is therefore accepted and cached, yet register() and every later logger() call for that name throw a TypeError on return. Always register a ZubZet\Framework\Logger\Logger.

Logger Types

Database Logger

Stores log records in the z_interaction_log database table. This is the default logger type.

logger_type = database

Each log entry is stored as a row with the following columns:

Column Type Description
id INT Auto-incrementing primary key
text MEDIUMTEXT The plain log message
value MEDIUMTEXT Full log record as a JSON string (see below)
userId INT ID of the currently logged-in user (nullable)
userId_exec INT ID of the executing user when using "login as" (nullable)
created TIMESTAMP Timestamp of the log entry

If the database connection is not available or the insert fails (for example a missing table mid-migration), the entry is silently skipped. Nothing purges z_interaction_log, so delete old rows yourself.

value Column Structure

The value column contains the JSON-encoded Monolog record. The processor adds traceId, file, line, class and function to extra (omitted below), and the environment keys userId, execUserId and source ("web" or "cli") are appended at write time:

{
    "message": "User logged in",
    "context": { "userId": 42 },
    "level": 200,
    "level_name": "INFO",
    "channel": "zubzet",
    "datetime": { "date": "2026-04-08 12:00:00.000000", "timezone_type": 3, "timezone": "UTC" },
    "extra": {
        "userId": 42,
        "execUserId": 42,
        "source": "web"
    }
}

Context values are not normalized. The record is encoded with JSON_UNESCAPED_UNICODE, JSON_UNESCAPED_SLASHES, JSON_INVALID_UTF8_SUBSTITUTE and JSON_THROW_ON_ERROR; if encoding fails, a fallback record containing only the message and the encoding error is stored instead.


Stream Logger

Writes log records as JSON to a file or PHP stream, one record per line.

logger_type = stream
logger_stream_url = php://stderr

logger_stream_url accepts any valid PHP stream URL or file path (relative paths resolve against the working directory):

logger_stream_url = php://stderr
logger_stream_url = php://stdout
logger_stream_url = /var/log/app.log
logger_stream_url = z_config/app.log

Each log entry is a single JSON object followed by a newline character (an empty context or extra is written as {}). Missing directories are created and there is no rotation; the php://stderr default ends up in the PHP or webserver error log. The environment keys are appended to extra automatically before formatting:

{"message":"User logged in","context":{"userId":42},"level":200,"level_name":"INFO","channel":"zubzet","datetime":"2026-04-08 12:00:00","extra":{"userId":42,"execUserId":42,"source":"web"}}

Example

# z_config/z_settings.ini
logger_type = database
logger_level = info
public function action_order(Request $req, Response $res) {
    $orderId = model("order")->createOrder($req->getPost("items"));

    logger()->info("Order placed", ["orderId" => $orderId]);

    return $res->success(["orderId" => $orderId]);
}