README

ext-tui

A PHP C extension for building terminal user interfaces with component-based architecture and Yoga flexbox layout.

Features

• Flexbox Layout: Facebook's Yoga layout engine for CSS-like flexbox positioning
• Component-Based: Build UIs with ContainerNode and ContentNode components
• Full UTF-8 Support: Proper handling of Unicode text including CJK wide characters
• Rich Text Styling: Bold, italic, underline, colors (RGB), and more
• Keyboard Input: Full keyboard event handling with modifiers (Ctrl, Alt, Shift)
• Mouse Support: Click, scroll, and drag events with hit testing
• Terminal Resize: Automatic layout recalculation on terminal resize
• Clipboard: OSC 52 clipboard read/write (works over SSH)
• Hyperlinks: Clickable OSC 8 terminal hyperlinks
• Bracketed Paste: Detect and handle pasted text
• Focus Management: Tab navigation, focus groups, focus traps
• Drawing Primitives: Lines, rectangles, circles, ellipses, triangles
• Canvas Graphics: High-resolution drawing with Braille, block, or ASCII modes
• Animation: Easing functions, interpolation, color gradients
• Sprites: Frame-based animated sprites with collision detection
• Tables: Formatted table rendering with alignment and borders
• Progress Indicators: Progress bars, busy bars, and spinners
• Timers: Interval-based callbacks for animations and updates
• High Performance: All rendering done in C with minimal PHP overhead

Requirements

• PHP 8.0+
• C compiler with C++20 support (for Yoga)
• Unix-like operating system (macOS, Linux)
• Terminal with UTF-8 support

Installation

From Source

# Clone the repository git clone https://github.com/xocoder/ext-tui.git cd ext-tui # Build the extension phpize ./configure --enable-tui make # Run tests make test # Install (requires root) sudo make install # Add to php.ini echo "extension=tui.so" >> $(php -i | grep "Loaded Configuration File" | cut -d' ' -f5)

Verify Installation

php -m | grep tui # Output: tui php -r "var_dump(tui_get_terminal_size());" # Output: array(2) { [0]=> int(80) [1]=> int(24) }

Quick Start

Hello World

<?php use Xocdr\Tui\Ext\ContainerNode; use Xocdr\Tui\Ext\ContentNode; $instance = tui_render(function() { $box = new ContainerNode(['padding' => 1, 'borderStyle' => 'round']); $box->addChild(new ContentNode(['content' => 'Hello, World!', 'bold' => true, 'color' => [100, 255, 100]])); return $box; }); $instance->waitUntilExit();

Interactive Counter

<?php use Xocdr\Tui\Ext\ContainerNode; use Xocdr\Tui\Ext\ContentNode; $count = 0; $instance = tui_render(function() use (&$count) { $box = new ContainerNode([ 'flexDirection' => 'column', 'padding' => 2, 'gap' => 1 ]); $box->addChild(new ContentNode(['content' => "Counter: $count", 'bold' => true])); $box->addChild(new ContentNode(['content' => "Press UP/DOWN to change, Ctrl+C to exit", 'dim' => true])); return $box; }, [ 'fullscreen' => true, 'exitOnCtrlC' => true ]); tui_set_input_handler($instance, function($key) use (&$count, $instance) { if ($key->upArrow) $count++; if ($key->downArrow) $count--; $instance->rerender(); }); $instance->waitUntilExit();

Drawing with Canvas

<?php // Create a high-resolution canvas using Braille characters $canvas = tui_canvas_create(80, 40, "braille"); // Draw shapes tui_canvas_circle($canvas, 40, 20, 15); tui_canvas_line($canvas, 0, 0, 80, 40); // Render to strings $lines = tui_canvas_render($canvas); foreach ($lines as $line) { echo $line . "\n"; }

Progress Bar with Buffer

<?php $buffer = tui_buffer_create(80, 24); for ($i = 0; $i <= 100; $i += 5) { tui_buffer_clear($buffer); tui_render_progress_bar($buffer, 0, 0, 40, $i / 100); tui_buffer_render($buffer); usleep(100000); }

Documentation

Full documentation is available in the docs/ folder:

Manual (Tutorials & Guides)

• Getting Started - Installation and first app
• Components & Layout - ContainerNode, ContentNode, flexbox layouts
• Styling - Colors, text attributes, borders
• Input Handling - Keyboard events, focus, resize
• Drawing - Buffers, canvas, primitives, sprites, tables
• Animation - Easing, interpolation, effects

Reference

• Functions - Complete function reference
• Classes - ContainerNode, ContentNode, Key, Instance
• Constants - TUI_EASE_, TUI_CANVAS_, etc.

Specifications

• ext-tui Specification - Complete C extension specification
• xocdr/tui Specification - PHP library specification

API Overview

Application Lifecycle

tui_render(callable $component, array $options = []): TuiInstance tui_rerender(TuiInstance $instance): void tui_unmount(TuiInstance $instance): void tui_wait_until_exit(TuiInstance $instance): void

Event Handlers

tui_set_input_handler(TuiInstance $instance, callable $handler): void tui_set_focus_handler(TuiInstance $instance, callable $handler): void tui_set_resize_handler(TuiInstance $instance, callable $handler): void tui_set_tick_handler(TuiInstance $instance, callable $handler): void

Focus Management

tui_focus_next(TuiInstance $instance): void tui_focus_prev(TuiInstance $instance): void tui_get_focused_node(TuiInstance $instance): ?array

Timers

tui_add_timer(TuiInstance $instance, int $intervalMs, callable $callback): int tui_remove_timer(TuiInstance $instance, int $timerId): void

Terminal Info

tui_get_terminal_size(): array // [width, height] tui_get_size(TuiInstance $instance): ?array tui_is_interactive(): bool tui_is_ci(): bool

Text Utilities

tui_string_width(string $text): int tui_wrap_text(string $text, int $width): array tui_truncate(string $text, int $width, string $ellipsis = "...", string $position = "end"): string tui_pad(string $text, int $width, string $align = "l", string $pad_char = " "): string

Drawing Buffers

tui_buffer_create(int $width, int $height): resource tui_buffer_clear(resource $buffer): void tui_buffer_render(resource $buffer): void

Drawing Primitives

tui_draw_line(resource $buffer, int $x1, int $y1, int $x2, int $y2, array $style): void tui_draw_rect(resource $buffer, int $x, int $y, int $w, int $h, array $style): void tui_fill_rect(resource $buffer, int $x, int $y, int $w, int $h, array $style): void tui_draw_circle(resource $buffer, int $cx, int $cy, int $r, array $style): void tui_fill_circle(resource $buffer, int $cx, int $cy, int $r, array $style): void tui_draw_ellipse(resource $buffer, int $cx, int $cy, int $rx, int $ry, array $style): void tui_fill_ellipse(resource $buffer, int $cx, int $cy, int $rx, int $ry, array $style): void tui_draw_triangle(resource $buffer, int $x1, int $y1, int $x2, int $y2, int $x3, int $y3, array $style): void tui_fill_triangle(resource $buffer, int $x1, int $y1, int $x2, int $y2, int $x3, int $y3, array $style): void

Canvas (High-Resolution Drawing)

tui_canvas_create(int $width, int $height, string $mode = "braille"): resource tui_canvas_set(resource $canvas, int $x, int $y): void tui_canvas_unset(resource $canvas, int $x, int $y): void tui_canvas_toggle(resource $canvas, int $x, int $y): void tui_canvas_get(resource $canvas, int $x, int $y): bool tui_canvas_clear(resource $canvas): void tui_canvas_line(resource $canvas, int $x1, int $y1, int $x2, int $y2): void tui_canvas_rect(resource $canvas, int $x, int $y, int $w, int $h): void tui_canvas_fill_rect(resource $canvas, int $x, int $y, int $w, int $h): void tui_canvas_circle(resource $canvas, int $cx, int $cy, int $r): void tui_canvas_fill_circle(resource $canvas, int $cx, int $cy, int $r): void tui_canvas_set_color(resource $canvas, int $r, int $g, int $b): void tui_canvas_get_resolution(resource $canvas): array tui_canvas_render(resource $canvas): array

Animation

tui_ease(float $t, string $easing = "linear"): float tui_lerp(float $a, float $b, float $t): float tui_lerp_color(array $a, array $b, float $t): string tui_gradient(array $from, array $to, int $steps): array tui_color_from_hex(string $hex): array

Tables

tui_table_create(array $headers): resource tui_table_add_row(resource $table, array $cells): void tui_table_set_align(resource $table, int $column, bool $right_align): void tui_table_render_to_buffer(resource $buffer, resource $table, int $x, int $y, string $border = "single"): int

Progress Indicators

tui_render_progress_bar(resource $buffer, int $x, int $y, int $width, float $progress): void tui_render_busy_bar(resource $buffer, int $x, int $y, int $width, int $frame, string $style_name = "pulse"): void tui_spinner_frame(string $type, int $frame): string tui_spinner_frame_count(string $type): int tui_render_spinner(resource $buffer, int $x, int $y, string $type, int $frame): void

Sprites

tui_sprite_create(array $frames, string $name = "default", bool $loop = true): resource tui_sprite_update(resource $sprite, int $delta_ms): void tui_sprite_set_animation(resource $sprite, string $name): bool tui_sprite_set_position(resource $sprite, int $x, int $y): void tui_sprite_flip(resource $sprite, bool $flipped): void tui_sprite_set_visible(resource $sprite, bool $visible): void tui_sprite_render(resource $buffer, resource $sprite): void tui_sprite_get_bounds(resource $sprite): array tui_sprite_collides(resource $a, resource $b): bool

Classes

All classes are in the Xocdr\Tui\Ext namespace.

ContainerNode

Flexbox container component.

use Xocdr\Tui\Ext\ContainerNode; $box = new ContainerNode([ 'flexDirection' => 'column', // 'row', 'column', 'row-reverse', 'column-reverse' 'alignItems' => 'center', // 'flex-start', 'center', 'flex-end', 'stretch' 'justifyContent' => 'center', // 'flex-start', 'center', 'flex-end', 'space-between', 'space-around', 'space-evenly' 'width' => '100%', 'height' => 10, 'padding' => 1, 'gap' => 1, 'borderStyle' => 'round', // 'single', 'double', 'round', 'bold' 'borderColor' => [100, 150, 255], 'focusable' => true, ]); $box->addChild($child);

ContentNode

Text display component.

use Xocdr\Tui\Ext\ContentNode; $text = new ContentNode([ 'content' => 'Hello!', 'color' => '#00ff00', // or [0, 255, 0] 'backgroundColor' => [50, 50, 50], 'bold' => true, 'italic' => true, 'underline' => true, 'dim' => false, 'inverse' => false, 'strikethrough' => false, ]);

Instance

Running TUI application handle.

$instance->rerender(); // Force re-render $instance->unmount(); // Stop and cleanup $instance->waitUntilExit(); // Block until exit $instance->exit(0); // Request exit with code

Key

Keyboard event object (passed to input handlers).

$key->key // string: character pressed $key->upArrow // bool $key->downArrow // bool $key->leftArrow // bool $key->rightArrow // bool $key->return // bool (enter key) $key->escape // bool $key->backspace // bool $key->delete // bool $key->tab // bool $key->ctrl // bool $key->alt // bool $key->meta // bool $key->shift // bool

Constants

Mouse Tracking Modes

TUI_MOUSE_MODE_OFF, TUI_MOUSE_MODE_CLICK, TUI_MOUSE_MODE_BUTTON, TUI_MOUSE_MODE_ALL

String-Based Options

Many functions use string values instead of constants:

• Easing: "linear", "in_quad", "out_quad", "in_out_quad", "in_cubic", "out_cubic", etc.
• Canvas modes: "braille", "block", "ascii"
• Spinner types: "dots", "line", "bounce", "circle"
• Clipboard targets: "clipboard", "primary", "secondary"

See Constants Reference for complete list.

Known Limitations

• macOS/Linux only: Uses POSIX APIs (termios, poll, signals)
• No Windows support: Consider WSL for Windows users

See docs/limitations.md for full details.

Related Projects

• xocdr/tui - PHP library with hooks wrapping ext-tui
• xocdr/tui-widgets - Pre-built widget components

License

MIT License - see LICENSE

Credits

• Yoga - Facebook's flexbox layout engine
• Inspired by Ink for Node.js