Debug Your App

Because the rendered frame owns the terminal, you can't echo or var_dump into it — Phui gives you dedicated tools instead.

Overview

Two tools stand in for printing into the frame. A debug bar — an in-terminal overlay you toggle at runtime — shows live state and surfaces PHP errors without disturbing the layout. A file logger writes structured lines to a file you tail alongside the running app, for anything the overlay can't hold.

The debug bar

Enable it on the Screen, then toggle it at runtime with F12 (the default toggleDebug binding):

Screen::mount(App::class)->debug()->run();

The overlay shows the live element tree, frame timing, and logs, in cyclable panes:

• Elements — the tree as Phui reconciled it, each element with its layout box. Walk it with j/k, switch layers with x. The first thing to reach for when layout is not doing what you expect.
• Metrics — per-frame build, layout and paint costs, idle time, and whether frames actually rendered.
• Logs — everything written through the logger, newest last.

It renders in its own layer, so while open it holds focus and its keys do not leak into your app. Metrics are only collected with debug() on — a plain run() pays nothing for any of it.

The file logger

A Logger writes to a file that outlives the terminal being restored — for longer output, or errors that would otherwise scramble a raw-mode screen.

Log to a file

Point the logger at a file and tail it in another terminal:

use Phui\Debug\Logger;

Logger::configure(__DIR__.'/phui.log');

Logger::info('mounted dashboard');
Logger::debug("rows: {$count}");

tail -f phui.log

Logs written this way also appear in the debug bar's Logs pane.