Raydium

Appearance

🛠 Debugging ​

⚠️ WARNING: Never enable debugging in production environments, as it exposes sensitive data.

📌 Overview ​

Debugging in the framework is primarily handled by the Terminate class. This ensures that errors are properly logged, displayed, and handled based on the environment settings.

When an error occurs, the framework provides a structured debug page with relevant information.

📌 Features ​

  • Captures exceptions and renders a clean debug UI.
  • Displays stack traces only if debugging is enabled.
  • Provides links to Retry, Go Home, or Log In (if applicable).
  • Uses Terminate for consistent error handling.

🛠 Why This Approach? ​

  • Consistent Debugging: Uses Terminate to maintain uniform error handling.
  • Security First: Only shows debugging info if explicitly enabled.
  • User-Friendly: Provides retry/home/login links where applicable.

🚨 What Happens During an Error? ​

When an error occurs:

  1. Terminate Captures the Exception
    • It processes the exception and determines the appropriate HTTP status code.
  2. An Error Page is Displayed
    • A user-friendly error message is shown.
    • In debug mode (or dev environments), additional stack trace information is available.
  3. The Exception is Logged
    • The error details are sent to a logging system (e.g., Sentry, error logs).
  4. The Script is Terminated
    • The application stops execution safely.

🔍 Debugging Modes ​

1️⃣ Production Mode (Default) ​

  • The error page is minimal (no stack trace is shown).
  • Only essential error messages are displayed.
  • Exceptions are logged silently for later debugging.

2️⃣ Debug Mode (Enabled Manually) ​

  • A detailed stack trace is shown on the error page.
  • Helps to quickly identify the root cause of an issue.
  • Debugging can be enabled via:
    php
    define('DEBUG_STACK_TRACE', true);
    or by setting the following in configs:
    php
    'terminate.debugger' => true,

Stack trace information will NOT show up in production environments
(i.e., ['secure', 'sec', 'production', 'prod']) unless DEBUG_STACK_TRACE is explicitly defined. Stack traces are typically available in other environments like dev, debug, etc.

⚠️ Use DEBUG_STACK_TRACE cautiously in production
It is an override meant for exceptional cases where debugging is necessary in production.
Enabling it may leak sensitive information and should generally be avoided.

📄 Debug Page Structure ​

When debugging is enabled, the error page includes:

  • Exception Message → A clear message about the error.
  • Stack Trace → A detailed trace showing where the error occurred.
  • Request Details → If available, shows request path and context.
  • Helpful Links:
    • Retry → Reload the current request.
    • Go Home → Navigate to the homepage.
    • Login (if applicable) → Redirects to the admin login page.
  • Other Errors →
    • In some cases, Terminate may not be available or able to handle an error.
    • These are usually handled by the error-handler in app.phpConfigurations.

📌 Enabling Debugging (Local Development) ​

To enable full debugging in local development:

php
define('DEBUG_STACK_TRACE', true);

or configure in app.php:

php
'terminate.debugger' => true,

📝 Summary ​

✅ Debugging is handled by the Terminate class.
✅ Errors are logged and displayed securely.
✅ Production mode hides stack traces to protect sensitive data.
✅ Debug mode provides full stack trace visibility for developers.

For further debugging, check log files or use tools like Sentry for remote monitoring. 🚀