Create Rich Text Terminal Interfaces with Solo Screen – Pure PHP Renderer

Overview

The Solo Screen repository provides a pure‑PHP terminal renderer for building rich‑text user interfaces in any PHP application. It was created to solve specific issues in Solo for Laravel and focuses on interpreting and rendering formatted text rather than handling input or process management.

Features

Pure PHP implementation : only depends on the Grapheme library.

Comprehensive ANSI support : handles cursor positioning, text styling, and screen operations.

Unicode / multibyte support : correctly processes UTF‑8 characters, including emojis and wide characters.

Buffer management : maintains separate buffers for text content and styles.

Character width handling : accurately calculates display width for CJK and other double‑width characters.

Scrolling functionality : supports vertical scrolling with proper content management.

Installation

Install via Composer:

composer require soloterm/screen

Requirements

PHP 8.1 or higher

mbstring extension

Basic Usage

Below is a simple usage example:

use SoloTerm\Screen\Screen;

// Create a screen with specific dimensions (columns, rows)
$screen = new Screen(80, 24);

// Write text with ANSI escape sequences
$screen->write("Hello, \e[1;32mWorld!\e[0m");

// Move the cursor and add more text
$screen->write("\e[5;10HPositioned text");

// Output the rendered content
echo $screen->output();

Core Concepts

Screen

The main class that coordinates all functionality, handling cursor positioning, content writing, and final rendering.

Buffers

PrintableBuffer : stores visible characters and manages width calculations.

AnsiBuffer : tracks style information such as color, bold, and underline.

ANSI Handling

Correctly interprets ANSI escape sequences, including cursor movement, text styling, screen clearing, line operations, and scrolling.

Advanced Features

Cursor Positioning

// Move cursor to row 5, column 10
$screen->write("\e[5;10H");

// Move cursor up 3 lines
$screen->write("\e[3A");

// Save and restore cursor position
$screen->write("\e7"); // save
$screen->write("More text");
$screen->write("\e8"); // restore

Text Styling

// Bold red text
$screen->write("\e[1;31mImportant message\e[0m");

// Background color
$screen->write("\e[44mBlue background\e[0m");

// 256‑color support
$screen->write("\e[38;5;208mOrange text\e[0m");

// True‑color (RGB)
$screen->write("\e[38;2;255;100;0mCustom color\e[0m");

Screen Operations

// Clear screen
$screen->write("\e[2J");

// Clear from cursor to end of line
$screen->write("\e[0K");

// Insert line
$screen->write("\e[2L");

// Scroll up
$screen->write("\e[2S");

Custom Integration

Respond to terminal queries by setting a callback:

$screen->respondToQueriesVia(function ($response) {
    // Process the response (e.g., cursor position)
    echo $response;
});

Example: Building a Simple UI

use SoloTerm\Screen\Screen;

$screen = new Screen(80, 24);

// Draw a border
$screen->write("┌" . str_repeat("─", 78) . "┐
");
for ($i = 0; $i < 22; $i++) {
    $screen->write("│" . str_repeat(" ", 78) . "│
");
}
$screen->write("└" . str_repeat("─", 78) . "┘");

// Add a title
$screen->write("\e[1;30H\e[1;36mMy Application\e[0m");

// Add some content
$screen->write("\e[5;5HWelcome to the application!");
$screen->write("\e[7;5HPress 'q' to quit.");

// Render
echo $screen->output();

Testing

The repository includes a comprehensive test suite with a visual comparison system. Run tests with:

composer test

Visual Testing

An innovative screenshot‑based testing method validates visual output against real terminal behavior. Enable screenshot testing via environment variables:

ENABLE_SCREENSHOT_TESTING=1 composer test

ENABLE_SCREENSHOT_TESTING=2 composer test