Luminova Framework

PHP Luminova: Debugging and Troubleshooting Application

Last updated: 2026-03-20 20:01:27

Debug Luminova applications with built-in tools for breakpoints, tracing, and data inspection to quickly identify issues and monitor execution flow.

Luminova provides a suite of tools and utilities to help developers debug applications efficiently. From lightweight breakpoints to tracing execution and inspecting data at multiple checkpoints, profiling, logging and error display. These tools make it easier to identify issues, monitor application flow, and ensure code behaves as expected in both development and production environments.


Track Breakpoint

The Luminova Tracer breakpoint is a lightweight utility that allows you to register breakpoints in your code and manually inspect the process during execution.

Register Breakpoint

You can register multiple debug checkpoints:

use Luminova\Debugger\Tracer;

function example(): array
{
    $users = Users::select();
    Tracer::breakpoint(1, $users, 'List users');

    $parsed = process($users);
    Tracer::breakpoint(2, $parsed, 'After processing users');

    $data = inspect($parsed);
    Tracer::breakpoint(3, $data, 'Inspect processed data', function (array $debug, array $points): void {
        // e.g., rollback a transaction or log state
    });

    return $data;
}

Inspect Breakpoint

Execute a function and trace a specific breakpoint:

use Luminova\Debugger\Tracer;

// Trigger break when reaching breakpoint 2
Tracer::trace(2);

// Call the example function
example();

// Retrieve all registered breakpoints
print_r(Tracer::getBreakpoints());

Note:If you do not call Tracer::trace(...) before executing the function, the registered breakpoints will be skipped.


Performance Profiling

Luminova comes with a built-in performance profiler to help you see how your application behaves as it runs. You don't need to install anything or wire up extra packages. Just enable it in your environment file:

debug.show.performance.profiling = true

Once it's on, Luminova will start tracking key performance data for every request.


How Profiling Works

In the browser:A small floating panel appears at the bottom of each page. It shows real-time metrics such as:

  • Number of files loaded
  • How many belong to Luminova's core
  • How many come from third-party libraries
  • Execution time
  • Memory usage

Click the panel to expand it and see deeper details. It's meant to show you what's slowing things down and where the load is coming from.

In CLI mode:After a command finishes, the profiler prints the same metrics directly to the terminal.

For API responses:Profiling data is logged as JSON using the metrics log level.This keeps API output clean while still giving you complete performance data in your logs.


Why It Matters

Good performance starts with knowing what actually happens inside your application. The profiler gives you visibility into:

  • Slow sections of your code
  • Heavy modules
  • Memory growth
  • Expensive third-party libraries
  • Unexpected file loads

Catching these early will save you headaches later, especially when your application grows.


Web Profiling Example

Web Performance Profiling Screenshot


CLI Profiling Example

CLI Performance Profiling Screenshot


Note:Keep the profiler on during development. When something feels slow, don't guess—check the panel. It's faster, clearer, and a lot more honest than relying on “it feels fine to me.”


Maintenance Mode

Maintenance mode is a simple way to take your app offline while you debug, update, or fix something without exposing errors to visitors. Instead of showing the real page, Luminova serves a clean maintenance screen.

To enable it, set this in your environment file:

app.maintenance.mode = true

Once this is on, every visitor is shown the maintenance page until you turn it off again.


Auto-Refresh While Waiting

If you want the browser to automatically check when your app is back online, set:

app.maintenance.retry = <seconds>

For example, app.maintenance.retry = 10 makes the page refresh every 10 seconds.This keeps users from constantly guessing when your site is working again.


Custom Maintenance Page

You can edit the default template here:

/app/Errors/Defaults/maintenance.php

You're free to redesign it, add branding, or keep it simple.

Important Note:

Keep the page light. Don't depend on modules, helpers, or features that may not load during maintenance. If they fail, the user will see an error instead of your maintenance message. Stick to plain PHP, HTML, and whatever basic styles you need.


Error Display

Error Debugging Display Screenshot

Luminova includes a strong error-handling system that catches fatal errors and shows a structured error page. This page gives you a clear breakdown of what failed, where it happened, and how the error reached that point. It's far easier to work with than a blank 500 screen or a raw PHP dump.


Custom Error Page

In Production

Visitors see a clean, professional message instead of raw error output. This keeps your app looking stable even during a crash, and prevents sensitive information from leaking to the public.

In Development

The same error page expands to show deeper diagnostic information such as stack traces, file paths, and call history. It gives you everything you need to trace the failure back to the exact line.


Debug Tracing

If you want even more detail, enable:

debug.show.tracer = true

This adds a full trace view that highlights the specific file, line, and part of the code responsible for the failure. When you're tracking down a stubborn bug, this extra visibility saves time.


Disabling the Custom Error Page

If you'd rather see raw PHP errors directly in the browser, you can turn off the custom error page:

debug.display.errors = true

This forces PHP to print errors straight to the output. It's simple and useful for quick local debugging, but it should never be on in production.

Note:Direct error display can expose sensitive data—paths, code, variables, even credentials in some cases. Always keep the custom error page active on live systems.


Framework Fails Silently?

In some cases, Luminova may return a 500 Internal Server Error without showing any message or writing to the log. This typically means the framework failed to load during its initial setup, which prevents it from handling or reporting the error.

Common Causes

  • Missing or corrupted Composer dependencies
  • Incorrect file or folder permissions

When this happens, the core initialization fails, and Luminova cannot register its error handling logic, making the issue invisible nor log issues.

How to Debug It

To identify the problem, temporarily enable PHP error display in your /public/index.php file:

// /public/index.php

<?php
declare(strict_types=1);

// Temporarily add the lines below for debugging
error_reporting(E_ALL);
ini_set('display_errors', '1');

use Luminova\Boot;
use Luminova\Routing\Prefix;

require_once __DIR__ . '/../system/Boot.php';
// ...

⚠️ Important:

Remove or disable these lines once the issue is resolved to avoid exposing errors in production.


Log Debugging

Luminova automatically stores application logs in the writeable/logs/ directory. These logs are categorized by severity level, such as:

  • info.log - General information messages
  • debug.log - Debug-level messages
  • error.log - Application errors
  • critical.log - Critical failures and exceptions

You can view these logs manually or use the command line to inspect them quickly.


Navigate to Project Root

On Production Server (Linux)
cd /var/www/example.com
On Development Server
Linux / macOS (XAMPP)
cd /Applications/XAMPP/xamppfiles/htdocs/example.com

Windows (XAMPP)

cd C:\xampp\htdocs\example.com

Windows (WAMP)

cd C:\wamp64\www\example.com

Generic Windows (Custom Folder)

cd D:\projects\example.com

Replace example.com with your actual project folder name. Use the path that matches your setup. If unsure, check where your local server hosts your project files.


View Logs from the Command Line

On Linux / macOS

To read a specific log file, you can use cat, tail, or less to view logs:

# View the entire file
cat writeable/logs/info.log

# View the last 20 lines
tail -n 20 writeable/logs/error.log

# Follow new log entries in real time
tail -f writeable/logs/debug.log

# Scrollable view
less writeable/logs/critical.log

On Windows (CMD or PowerShell)

Use type, Get-Content, or more:

:: View entire file
type writeable\logs\info.log

:: View last lines (PowerShell)
Get-Content writeable\logs\error.log -Tail 20

:: Follow logs in real-time (PowerShell)
Get-Content writeable\logs\debug.log -Wait

:: Scrollable view (CMD)
more writeable\logs\critical.log

Tip: For continuous monitoring in development or production, use tail -f (Linux/macOS) or Get-Content -Wait (PowerShell).