Error Handling & Logs

Error Strategy: Procedural vs. Exceptional

Pragma CMS is built on a Procedural Error Model. To maximize execution speed and maintain a predictable control flow, the core engine avoids using Exceptions for predictable failures.

The Pragma Rule: If a failure is expected (file not found, invalid input, database timeout), the function must return false, null, or an error code.
Why? Exceptions break the "Happy Path" of the CPU, are significantly more expensive to process, and often lead to spaghetti try/catch nests that obscure the actual logic.

1. Core Error API

`logError()`

The primary engine for recording system misbehavior.

PHP

logError(string $message, string $level = 'ERROR', bool $forUser = false)

Performance: The function performs a single file_put_contents with LOCK_EX. It is designed to be high-throughput.
Routing:
- level: ERROR/WARNING: Appended to SITE_DIR/storage/logs/application.log.
- forUser: true: Injects the message into the $page->errors stack for the current render cycle.

`displayError()`

Triggers an immediate script termination with a contextual HTTP response.

State Detection: If is_api_request() is true, it forces a JSON payload. Otherwise, it triggers the cascading template loader to find the most relevant error.php (Theme > Site > Core).
Exit Strategy: It cleans all active output buffers (ob_end_clean) before exiting to ensure no partial or sensitive data is sent to the client.

2. Environment Hardening (Debug Mode)

Pragma CMS provides a granular Debug Mode that can be toggled independently at the Site level or the Platform level via the Admin settings.

Production Mode (Debug OFF)

When debug_mode is set to 0:

PHP: display_errors is disabled. All low-level engine warnings are suppressed from the UI.
Logging: Errors are silently flushed to php-error.log.
Twig: The template engine enables strict filesystem caching (/storage/cache/twig) to maximize rendering performance.

Development Mode (Debug ON)

When debug_mode is set to 1:

PHP: Full error reporting is enabled (E_ALL). Errors are printed directly to the screen for immediate feedback.
Twig: The cache is disabled (cache => false). Twig's debug mode is activated, allowing the use of the {{ dump() }} helper in templates.
Assets: If the system-wide DEV_MODE constant is also active, core assets are automatically re-synchronized with the public directory on every page load.

3. Log Architecture

Pragma CMS segregates logs into two distinct streams to accelerate troubleshooting:

Log File	Content
`application.log`	High-level application logic errors, failed API calls, and custom `logError()` messages.
`php-error.log`	Low-level PHP engine warnings, notices, and fatal crashes (Parse errors, Memory limits).

Pro Tip: During development, keep a terminal open with tail -f storage/logs/*.log to monitor both streams in real-time.

4. Maintenance & Cleanup

To prevent log files from exhausting server disk space, Pragma provides two diagnostic paths:

Maintenance Dashboard: Admin > Tools > Maintenance provides a real-time visual of log sizes and a manual "Clear" trigger.
CLI Garbage Collection: For automated DevOps workflows, use the included shell script: bash scripts/cli/clear_logs.sh