Download the PHP package soloterm/screen without Composer

Solo Screen

Screen is a terminal renderer written in pure PHP. It powers Solo for Laravel and can be used to build rich text-based user interfaces in any PHP application.

[!NOTE] Screen is a library intended to be integrated into PHP applications. It is not a standalone terminal application.

About terminal renderers

A terminal renderer processes text and ANSI escape sequences to create a virtual representation of terminal output. Unlike a full terminal emulator, Screen focuses specifically on correctly interpreting and rendering text content with formatting rather than handling input, interactive sessions, or process management.

Terminal renderers interpret escape sequences to:

• Track cursor position
• Apply text colors and styles (bold, underline, etc.)
• Manage screen content
• Handle special character sets
• Generate a final rendered output

Screen implements this functionality in pure PHP, allowing developers to build terminal user interfaces without relying on external dependencies or native code.

Why this exists

Screen was originally created to solve a specific problem in Solo for Laravel.

Solo provides a TUI (Text User Interface) that runs multiple processes simultaneously in separate panels, similar to tmux. However, when these processes output ANSI escape codes for cursor movement and screen manipulation, they could potentially "break out" of their visual containers and interfere with other parts of the interface.

To solve this problem, Screen creates a virtual terminal buffer where:

1. All ANSI operations (cursor movements, color changes, screen clears) are safely interpreted within an isolated environment
2. The final rendered state is captured after all operations are processed
3. Only the final visual output is displayed to the user's terminal

This approach provides complete control over how terminal output is rendered, ensuring that complex ANSI operations stay contained within their designated areas. While initially built for Solo, Screen has evolved into a standalone library that can be used in any PHP application requiring terminal rendering.

Features

• Pure PHP Implementation: Only one dependency (Grapheme, another Solo library)
• Comprehensive ANSI Support: Handles cursor positioning, text styling, and screen manipulation
• Unicode/Multibyte Support: Properly handles UTF-8 characters including emojis and wide characters
• Buffer Management: Maintains separate buffers for text content and styling
• Character Width Handling: Correctly calculates display width for CJK and other double-width characters
• Scrolling: Support for vertical scrolling with proper content management
• Relative Positioning: Output can be rendered at any position in a parent TUI without interference

Installation

Install via Composer:

Requirements

• PHP 8.1 or higher
• mbstring extension

Basic usage

Here's a simple example of using Screen:

Core concepts

Screen operates with several key components:

Screen

The main class that coordinates all functionality. It takes care of cursor positioning, content writing, and rendering the final output.

Buffers

Screen uses multiple buffer types to track content and styling:

• PrintableBuffer: Stores visible characters and handles width calculations
• AnsiBuffer: Tracks styling information (colors, bold, underline, etc.)

ANSI processing

Screen correctly interprets ANSI escape sequences for:

• Cursor movement (up, down, left, right, absolute positioning)
• Text styling (colors, bold, italic, underline)
• Screen clearing and line manipulation
• Scrolling

Architecture

Screen uses a dual-buffer architecture to separate content from styling:

• AnsiParser: A state machine that splits input into printable text and ANSI escape sequences
• Proxy: Coordinates writes to both buffers simultaneously, keeping them in sync
• PrintableBuffer: Stores visible characters, handles grapheme clusters and wide character width calculations
• AnsiBuffer: Stores styling as efficient bitmasks, with support for 256-color and RGB

This separation allows Screen to efficiently track what changed and optimize rendering.

Advanced features

Rendering at arbitrary positions (popup windows, panels)

When building TUIs with multiple Screen instances rendered at different positions (like popup windows or panels), you need to handle cursor positioning carefully. Screen's output() method uses relative cursor positioning to avoid the "pending wrap state" problem that causes rendering issues across different terminals.

The pending wrap problem

When a line is filled to exactly the terminal width, terminals enter a "pending wrap" state. The behavior of \n and \r in this state varies between terminal emulators:

• iTerm2: A newline after a full line moves down one row
• Ghostty: May move down two rows or position content incorrectly

This inconsistency can cause content to appear offset by an entire screen width in some terminals.

How Screen solves this

Screen's output() method uses DEC save/restore cursor (DECSC/DECRC) with cursor down (CUD) sequences instead of newlines:

This approach:

• Avoids pending wrap entirely — no \n characters between lines means wrap state doesn't matter
• Uses relative positioning — output renders correctly at any cursor position in a parent TUI
• Works consistently — same behavior in iTerm2, Ghostty, and other terminals

Rendering a Screen at a specific position

To render a Screen at a specific position in your TUI:

The Screen will render its content starting from wherever the cursor is positioned, with each line placed relative to that origin point.

Differential rendering

For high-performance applications like TUIs with frequent updates, Screen supports differential rendering that only outputs changed lines:

This is particularly useful when building interfaces that update at high frame rates (e.g., 40 FPS) where re-rendering the entire screen would be wasteful.

Cursor positioning

Text styling

Screen manipulation

Supported ANSI codes

Screen supports a comprehensive set of ANSI escape sequences:

Cursor movement (CSI sequences)

Erase functions

Scrolling

Text styling (SGR - Select Graphic Rendition)

Custom integrations

You can respond to terminal queries by setting a callback:

[!NOTE] This is still a work in progress. We need some more tests / use cases here.

Example: building a simple UI

Handling unicode and wide characters

Screen properly handles Unicode characters including emoji and CJK characters that take up multiple columns:

Testing

Screen includes a comprehensive test suite with visual comparison testing that validates output against real terminal behavior.

Available test commands

You can pass additional PHPUnit options using --:

Visual testing

Screen employs screenshot-based testing that compares rendered output against real terminal behavior. The system supports both iTerm2 and Ghostty terminals to ensure cross-terminal compatibility.

How it works:

1. The test renders content in a real terminal (iTerm2 or Ghostty)
2. It captures a screenshot using macOS's CGWindowListCreateImage API
3. It runs the same content through the Screen renderer
4. It captures another screenshot
5. It compares the screenshots pixel-by-pixel using ImageMagick

This ensures Screen's rendering accurately matches real terminal behavior for:

• Multi-byte characters and emoji
• Complex ANSI formatting
• Cursor movements and positioning
• Scrolling behavior
• Line wrapping
• Terminal-specific edge cases (like pending wrap state)

Requirements for visual testing

• macOS
• iTerm2 or Ghostty terminal
• ImageMagick (brew install imagemagick)

composer test:screenshots and composer test:missing launch fresh terminal relay windows to keep capture dimensions consistent with CI. iTerm is resized automatically to 180x32; Ghostty is opened to a calibrated window size and prompts if dimensions still need adjustment.

Fixture structure

Fixtures are stored per-terminal to account for rendering differences:

When running tests without screenshot generation, the system uses stored fixtures for comparison, making tests fast and suitable for CI/CD pipelines. In CI (where no terminal is available), iTerm fixtures are used since we validate that iTerm and Ghostty fixtures are identical.

CI Behavior

The Tests workflow enforces fixture hygiene and parity across a Linux PHP matrix:

• Runs on ubuntu-latest with PHP 8.1, 8.2, 8.3, 8.4, and 8.5
• Fails the job if PHPUnit output reports missing fixtures (Fixture with correct content does not exist or Fixture does not exist for)
• Runs composer test:fixtures after tests to enforce cross-terminal fixture parity and required dimensions

Current workflow action majors are modernized to avoid stale runtime warnings:

• actions/checkout@v6
• actions/cache@v5
• stefanzweifel/git-auto-commit-action@v7

Platform Caveats

Two specific multibyte parity edge cases are intentionally validated on macOS only and skipped on non-Darwin runners:

• MultibyteTest::test_line_wrapping_with_multibyte
• ReplayCorpusTest::multibyte_cursor_transcript_matches_full_replay_under_random_byte_chunking

Contributing

Contributions are welcome! Please feel free to submit a pull request.

License

The MIT License (MIT).

Support

This is free! If you want to support me:

• Check out my courses:
  • Database School
  • Screencasting
• Help spread the word about things I make

Related Projects

Screen is part of the SoloTerm ecosystem of Laravel and PHP development tools:

• Solo - All-in-one Laravel command for local development
• Dumps - Laravel command to intercept dumps
• Grapheme - Unicode grapheme width calculator
• Notify - PHP package for desktop notifications via OSC escape sequences
• Notify Laravel - Laravel integration for soloterm/notify
• TNotify - Standalone, cross-platform CLI for desktop notifications
• VTail - Vendor-aware tail for Laravel logs

Credits

Solo Screen was developed by Aaron Francis. If you like it, please let me know!

• Twitter: https://twitter.com/aarondfrancis
• Website: https://aaronfrancis.com
• YouTube: https://youtube.com/@aarondfrancis
• GitHub: https://github.com/aarondfrancis