Console Error Debugging

🎯 Probably the Only One!

The only PHP framework with native, built-from-scratch interactive error debugging in the console!

While other frameworks like Laravel rely on external tools like PsySH for interactive console debugging, Larafony implements its own sophisticated debug session system. When an exception occurs in your console commands, you don't just get a stack trace and exit—you get an interactive REPL-like experience where you can explore frames, inspect variables, view source code, and understand the error context without leaving your terminal or installing external dependencies.

This is the same beautiful, web-like debugging experience you get in browsers... but available in your console! 😎

Native Implementation Interactive Session Frame Inspection Variable Explorer Source Viewer

What Makes This Unique?

🚀 Native, Built-in Implementation

Unlike other frameworks that rely on external packages like PsySH, Larafony's console debugger is built from scratch and deeply integrated into the framework. Zero external dependencies, zero configuration, just pure framework magic!

Key Features

• Interactive Debug Session - Drop into a REPL-like interface when exceptions occur

• Command-Based Exploration - Type commands to explore stack traces, frames, variables, and source code

• Automatic Environment Detection - Detects CLI vs web mode via php_sapi_name()

• Beautiful Console Output - Color-coded, syntax-highlighted display

• Frame Navigation - Jump between stack frames to understand execution flow

• Variable Inspection - View all variables available in each frame

• Source Code Display - See code snippets with context around errors

• Fatal Error Recovery - Catches shutdown errors (E_ERROR, E_PARSE, E_CORE_ERROR, etc.)

How It Works

Automatic Registration

The ErrorHandlerServiceProvider automatically detects if your application is running in CLI mode and registers the appropriate handler. No configuration needed!

// In ErrorHandlerServiceProvider::register()
$isConsole = php_sapi_name() === 'cli';

if ($isConsole) {
// Register console error handler with factory
$factory = new ConsoleRendererFactory($container);
$renderer = $factory->create();

$handler = new ConsoleHandler(
$renderer,
fn(int $exitCode) => exit($exitCode)
);

$container->set(BaseHandler::class, $handler);
} else {
// Register web error handler
$handler = new DetailedErrorHandler($viewManager, $debug);
$container->set(BaseHandler::class, $handler);
}

Service Provider Order

⚠️ Important: ConsoleServiceProvider must be registered before ErrorHandlerServiceProvider because it provides the OutputContract dependency.

// In bootstrap/console.php
$app->withServiceProviders([
HttpServiceProvider::class,
ConfigServiceProvider::class,
ConsoleServiceProvider::class, // ← Must come first
DatabaseServiceProvider::class,
ErrorHandlerServiceProvider::class, // ← Depends on ConsoleServiceProvider
]);

Interactive Debug Commands

When an exception occurs, you'll see a prompt where you can type commands:

$ php bin/larafony process:data

Processing data...

[ERROR] RuntimeException
Data processing failed: Invalid format

in /var/www/app/Commands/ProcessDataCommand.php:24

Debug mode: (type 'help' for available commands) > help

Available commands:
 trace - Show full stack trace
 frame N - Show details for frame N
 vars - Show variables in current frame
 source - Show source code around error
 env - Show environment information
 exit - Exit debug mode

Debug mode: (type 'help' for available commands) > trace

Stack trace:
 #0 ProcessDataCommand->processComplexData()
at /var/www/app/Commands/ProcessDataCommand.php:24

 #1 ProcessDataCommand->handle()
at /var/www/app/Commands/ProcessDataCommand.php:15

 #2 Kernel->handleCommand()
at /var/www/framework/src/Console/Kernel.php:42

Debug mode: (type 'help' for available commands) > frame 0

Frame #0: ProcessDataCommand->processComplexData()
File: /var/www/app/Commands/ProcessDataCommand.php:24

Source code:
 20 │
 21 │ private function processComplexData(): array
 22 │ {
 23 │ // This will trigger the console error handler
> 24 │ throw new \RuntimeException('Data processing failed: Invalid format');
 25 │ }
 26 │ }

Variables:
 $this = ProcessDataCommand {#42}
 $output = Output {#12}

Debug mode: (type 'help' for available commands) > env

Environment Information:
 PHP Version: 8.5.0
 Memory Usage: 4.2 MB / 512 MB
 Execution Time: 0.15s
 Operating System: Linux
 SAPI: cli

Debug mode: (type 'help' for available commands) > exit

abstract class BaseHandler
{
// Register PHP error/exception handlers
public function register(): void
{
set_error_handler([$this, 'handleError']);
set_exception_handler([$this, 'handleException']);
register_shutdown_function([$this, 'handleFatalError']);
}

// Convert PHP errors to exceptions
public function handleError(int $level, string $message, ...): bool
{
throw new ErrorException($message, 0, $level, $file, $line);
}

// Catch fatal errors during shutdown
public function handleFatalError(): void
{
$error = error_get_last();
if ($error !== null && $this->isFatalError($error['type'])) {
$this->handleException(new FatalError(...));
}
}

abstract public function handleException(Throwable $exception): void;
}

<?php

namespace App\Commands;

use Larafony\Framework\Console\Attributes\Command;
use Larafony\Framework\Console\Contracts\CommandContract;
use Larafony\Framework\Console\Contracts\OutputContract;

#[Command(name: 'test:error', description: 'Test console error handler')]
class TestErrorCommand implements CommandContract
{
public function __construct(private OutputContract $output)
{
}

public function handle(array $options = []): int
{
$this->output->info('About to trigger an exception...');

// This will activate the interactive debugger
throw new \RuntimeException('Test exception for debugging!');
}
}

php bin/larafony test:error