Cypht Logging System

Cypht uses Monolog as its logging backend. Monolog is a widely adopted, PSR-3 compliant PHP logging library that provides immediate, structured log output to multiple destinations — files, the PHP error log, syslog, and more — without buffering. It introduces proper severity levels (DEBUG, INFO, WARNING, ERROR, CRITICAL, …) so that production systems can suppress noise while still capturing what matters. Its only dependency is psr/log, keeping the addition lightweight and in keeping with Cypht's minimalist philosophy.

Architecture

How a log message flows

Application code
      │
      ▼
Hm_Debug::add($message, $type)
      │
      ├──► In-memory queue  ──► Browser debug panel (HTML pages, ENABLE_DEBUG=true)
      │
      └──► Hm_Logger (Monolog bridge)
                │
                ├──► ErrorLogHandler  (web SAPI only — apache/php-fpm error log)
                │
                └──► StreamHandler    (optional file, if LOG_FILE is set)

Messages are forwarded to Monolog immediately when Hm_Debug::add() is called, not at the end of the request. The in-memory queue is preserved for the browser debug panel and for backward compatibility with code that calls Hm_Debug::show().

Log level mapping

$type passed to Hm_Debug::add()	Monolog level
danger / error	ERROR
warning	WARNING
info / success	INFO
debug (or omitted)	DEBUG

---

Environment Variables

Add these to your .env file:

Variable	Default	Description
ENABLE_DEBUG	false	Master switch. Replaces the old hard-coded DEBUG_MODE. Set to true in development.
LOG_LEVEL	WARNING	Minimum level to emit. One of: ERROR, WARNING, INFO, DEBUG. Messages below this threshold are discarded.
LOG_FILE	(empty)	Absolute path to a log file. Leave empty to log to the PHP error log only.

Recommended configurations

Production

ENABLE_DEBUG=false
LOG_LEVEL=WARNING
LOG_FILE=/var/log/cypht/cypht.log

Development

ENABLE_DEBUG=true
LOG_LEVEL=INFO
LOG_FILE=

Deep debugging

ENABLE_DEBUG=true
LOG_LEVEL=DEBUG
LOG_FILE=/tmp/cypht-debug.log

Log level filtering

LOG_LEVEL setting	ERROR logged	WARNING logged	INFO logged	DEBUG logged
ERROR	✓	✗	✗	✗
WARNING	✓	✓	✗	✗
INFO	✓	✓	✓	✗
DEBUG	✓	✓	✓	✓

---

Configuration: Log File

If LOG_FILE is set, the directory must exist and be writable by the web server:

sudo mkdir -p /var/log/cypht
sudo chown www-data:www-data /var/log/cypht
sudo chmod 755 /var/log/cypht

When both LOG_FILE and the PHP error log are active, messages are written to both.

---

Usage in Code

Existing code — no changes required

All existing Hm_Debug::add() calls continue to work as before:

Hm_Debug::add('Database connection failed');            // defaults to DEBUG level
Hm_Debug::add('Database connection failed', 'danger');  // ERROR
Hm_Debug::add('Cache miss for sessions key', 'warning'); // WARNING
Hm_Debug::add('User authenticated successfully', 'info'); // INFO

Direct Monolog access

For new code that needs structured context or PSR-3 log methods directly:

use Monolog\Level;

// PSR-3 style with context arrays
Hm_Logger::error('Authentication failed', ['user' => $username, 'server' => $server]);
Hm_Logger::warning('Cache miss', ['key' => $cacheKey]);
Hm_Logger::info('Request processed', ['duration_ms' => $elapsed]);

// Raw Monolog instance (advanced)
$logger = Hm_Logger::getLogger();
$logger->critical('Unexpected shutdown', ['reason' => 'out of memory']);

Log level guidelines

Use the right severity so log noise stays manageable in production:

Situation	Type to use
Auth failures, DB errors, session failures, HMAC failures	danger (ERROR)
Config issues, cache misses, suspicious requests, missing translations	warning
Successful logins, config loaded, server connectivity info	info
Verbose trace data, per-request detail	debug

---

Browser Debug Panel

When ENABLE_DEBUG=true, a collapsible debug panel is automatically injected at the bottom of every HTML page response (not AJAX/JSON). It shows all queued Hm_Debug messages, colour-coded by type.

The panel is hidden by default and toggled with a Debug button in the bottom-right corner. It requires no external CSS or JavaScript — styles are inlined.

This replaces the older approach of relying on PHP's display_errors setting, which is typically off in production and is a security risk if accidentally enabled.

---

Backward Compatibility

What	Status
All Hm_Debug::add() call sites	✅ Unchanged — works as before
Hm_Debug::show()	✅ Still flushes queue to error_log
Module security guards (if (!defined('DEBUG_MODE')) { die(); })	✅ Preserved
In-memory message queue	✅ Still populated (used by debug panel)
DEBUG_MODE constant itself	✅ Still defined — now reads from ENABLE_DEBUG env var

---

Testing

Install dependencies

If upgrading an existing installation, run composer install first to pull in Monolog:

composer install

Verify Monolog is installed

composer show monolog/monolog

Troubleshooting

Debug panel does not appear

• Confirm ENABLE_DEBUG=true in .env
• Confirm you are viewing an HTML page, not an AJAX/JSON response
• Check the browser console for JavaScript errors

Nothing written to LOG_FILE

• Confirm the directory exists and is writable by the web process
• Check LOG_LEVEL — if set to ERROR, only errors are written

No output at all in the PHP error log

• Check LOG_LEVEL — set to INFO or DEBUG temporarily to confirm the pipeline works
• On php-fpm: tail -f /var/log/php-fpm/error.log
• On Apache: tail -f /var/log/apache2/error.log

---

References

• Monolog documentation
• PSR-3 Logger Interface
• GitHub issue #1027 — Improve error and message logging
• Pull Request