Console Error Debugging

Interactive, REPL-like debugging experience when exceptions occur in CLI commands

What Makes This Unique?

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

// 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:

Example Debug Session

Here's what you see when an exception occurs in a console command:

$ 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

Architecture

Core Components

BaseHandler Abstract Class

Provides common error handling functionality:

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;
}

Fatal Error Types

The handler catches these fatal errors:

• E_ERROR - Fatal run-time errors
• E_PARSE - Compile-time parse errors
• E_CORE_ERROR - Fatal errors during PHP's initial startup
• E_COMPILE_ERROR - Fatal compile-time errors
• E_USER_ERROR - User-generated error message
• E_USER_DEPRECATED - User-generated deprecation notice

Comparison with Other Solutions

Creating a Test Command

Try it yourself by creating a simple command that throws an exception:

<?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!');
    }
}

Run it with:

php bin/larafony test:error

You'll immediately drop into the interactive debug session!

Best Practices

• Development Only - The interactive debugger is perfect for development. In production, exceptions should be logged
• Explore Thoroughly - Use trace to see the full picture, then frame N to dive deep
• Check Variables - Always inspect variables with vars to understand state
• Exit Cleanly - Type exit to quit, or Ctrl+C for immediate termination
• Use for Learning - Great way to understand framework internals and execution flow

Future Enhancements

Planned improvements for the console debugger:

• Code execution in frame context (eval)
• Search within stack traces
• Export debug session to file
• Custom command extensions
• Integration with logging