AnsiKit

Tiny, easy-to-remember ANSI escape helper for building terminal UIs in PHP. Chainable API for styles/colors/cursor control, with a few handy components (Table, Banner, Progressbar etc.) and utilities.

Works any terminal that supports ANSI escapes (most modern terminals on macOS/Linux and Windows Terminal/ConEmu on Windows 10+).

Let's keep simple things simple. 😌
You don't need a whole framework to build a simple CLI app.

Features

• Colors: Foreground and background colors - standard 8/16 colors, 256-color, and truecolor (RGB, 24-bit)
• Text styles: bold, dim, italic, underline, inverse, hidden, strike-through
• Cursor control: movement, save/restore, show/hide, alternate screen buffer
• Components: Table, Banner, Progressbar, Spinner
• Writers: swap output target (stdout or in-memory for tests)
• Helpers: ANSI‑aware string length, simple input (line/multiline/confirm)
• PSR‑12, strict types, DI‑friendly, zero dependencies

A Quick Primer

Run the example demo: php examples/showcase.php.
This should render the following in dark mode terminal:

Check below the Examples section for more demos.

Installation

Requirements: PHP >= 8.2 and (composer)[https://getcomposer.org/]

composer require ajaxray/ansikit

Autoloads via PSR‑4 namespace Ajaxray\AnsiKit\.

Documentation

• Getting started: docs/index.md
• Core API: AnsiTerminal
• Components: Table, Banner, Progressbar, Spinner, Choice
• Support: Input, Str, Keypress, Util

Quick Start

<?php
require __DIR__ . '/vendor/autoload.php';

use Ajaxray\AnsiKit\AnsiTerminal;
use Ajaxray\AnsiKit\Components\{Table, Banner, Progressbar, Choice};

$t = new AnsiTerminal();
$t->clearScreen()->cursorHome();

$t->writeStyled("Hello PHP Ninja!\n", [AnsiTerminal::TEXT_BOLD, AnsiTerminal::FG_GREEN]);
$t->fg256(202)->bg256(235)->write("256-colors")->reset()->newline();
$t->fgRGB(255,165,0)->write("Truecolor (RGB)")->reset()->newline();

$table = new Table();
$table->setHeaders('Name','Age', 'Adult?')
    ->addRow('Anis','41', '✅')
    ->addRow('Fatima', '2.5', '❌')
    ->render();

$banner = new Banner();
$banner->render('Deploy Complete', ['Everything shipped!']);

$bar = new Progressbar();
$bar->renderLine(75, 100, 'Loading files...');

$choice = new Choice();
$selected = $choice->prompt('Choose deployment target:', ['Production', 'Staging', 'Development']);
$t->writeStyled("Selected: {$selected}\n", [AnsiTerminal::FG_GREEN]);

Usage Overview

Core: AnsiTerminal

Docs: AnsiTerminal

• Text attributes: TEXT_BOLD, TEXT_UNDERLINE, TEXT_STRIKE, etc.
• Foreground/background colors: standard (FG_RED), bright (FG_BRIGHT_GREEN), fg256($n), bg256($n), fgRGB($r,$g,$b), bgRGB(...)
• Cursor: cursorTo($row, $col), cursorUp($n), hideCursor(), saveCursor(), enableAltBuffer()
• Output: write($text), writeStyled($text, [..]), newline($n)

Chainable style example:

$t->style(AnsiTerminal::TEXT_BOLD, AnsiTerminal::FG_YELLOW)->write('Warning!')->reset()->newline();

Components

Table

Docs: Table

use Ajaxray\AnsiKit\Components\Table;

(new Table())
  ->setHeaders('Name','Age')
  ->addRow('Ada', '36')
  ->addRow('Linus', '54')
  ->render();

Banner

Docs: Banner

use Ajaxray\AnsiKit\Components\Banner;

(new Banner())->render('Deploy Complete', ['Everything shipped!', 'Tag: v1.2.3']);

Progressbar

Docs: Progressbar

use Ajaxray\AnsiKit\Components\Progressbar;

(new Progressbar())
  ->barStyle([AnsiTerminal::FG_GREEN])
  ->percentageStyle([AnsiTerminal::TEXT_BOLD])
  ->labelStyle([AnsiTerminal::FG_CYAN])
  ->borders('[', ']')
  ->renderLine(50, 100, 'Processing');

Spinner

Docs: Spinner

use Ajaxray\AnsiKit\Components\Spinner;

$s = new Spinner(); // or new Spinner(Spinner::ASCII)
echo $s->next(); // prints next frame

Choice

Docs: Choice

use Ajaxray\AnsiKit\Components\Choice;

// Basic usage (required choice)
$choice = new Choice();
$selected = $choice->prompt('Choose an option:', ['Option A', 'Option B', 'Option C']);
// Returns: 'Option A', 'Option B', or 'Option C'

// Optional choice (with Exit option)
$choice = new Choice();
$selected = $choice
  ->required(false)
  ->prompt('Select an action:', ['Deploy', 'Test', 'Rollback']);
// Returns: 'Deploy', 'Test', 'Rollback', or false (if Exit chosen)

// Styled choice
$choice = new Choice();
$selected = $choice
  ->promptStyle([AnsiTerminal::TEXT_BOLD, AnsiTerminal::FG_CYAN])
  ->optionStyle([AnsiTerminal::FG_GREEN])
  ->numberStyle([AnsiTerminal::FG_YELLOW])
  ->errorStyle([AnsiTerminal::FG_RED])
  ->exitStyle([AnsiTerminal::FG_BRIGHT_BLACK])
  ->prompt('Choose:', ['Option 1', 'Option 2']);

Helpers

Input

Docs: Input

use Ajaxray\AnsiKit\Support\Input;

$name = Input::line('Your name? [Anonymous] ', 'Anonymous');
$ok   = Input::confirm('Proceed?', true);
$bio  = Input::multiline("Enter bio. End with 'END'", 'END');

If the readline extension is available, Input::line() uses it for line editing/history; otherwise it falls back to STDIN.

Str

Docs: Str

use Ajaxray\AnsiKit\Support\Str;

$plain = Str::stripAnsi("\033[1;31mError\033[0m");
$len   = Str::visibleLength("Styled \033[1mtext\033[0m");

Util

Docs: Util

use Ajaxray\AnsiKit\Support\Util;
use Ajaxray\AnsiKit\AnsiTerminal;

$terminal = new AnsiTerminal();
Util::setTerminalTabTitle('Build in progress', $terminal);
Util::beep($terminal);

Keypress

Docs: Keypress

use Ajaxray\AnsiKit\Support\Keypress;

// Blocking read (returns a normalized key constant or single char)
$key = Keypress::listen();
if ($key === Keypress::KEY_UP) { /* move up */ }

// Non-blocking read with timeout (in milliseconds)
if ($key = Keypress::listenNonBlocking(100)) {
    // Works with arrows, ENTER/ESC/TAB/BACKSPACE, CTRL+A..Z, F1..F12, HOME/END/PgUp/PgDn, and more
    echo Keypress::getKeyName($key); // e.g., "CTRL+C", "UP ARROW", "'a'"
}

Writers

• StdoutWriter (default): writes to php://stdout or a provided stream
• MemoryWriter: buffer output for tests or capturing

use Ajaxray\AnsiKit\Writers\MemoryWriter;

$w = new MemoryWriter();
$t = new AnsiTerminal($w);
$t->write('hello');
echo $w->getBuffer(); // 'hello'

Examples

Run the example scripts to see things in action:

php examples/showcase.php   # basic styles, table, banner, bars
php examples/progress.php   # animated status + progress bar
php examples/input.php      # interactive input demo
php examples/choice.php     # interactive choice component demo
php examples/choice-menu.php # interactive menu system with choice
php examples/keypress.php    # interactive key handling demo
php examples/keypress-advanced.php # advanced key sequences, modifiers
php examples/util.php        # tab title + bell helper demo

More guides and examples: see docs/index.md.

Tips & Compatibility

• Windows 10+: use Windows Terminal, ConEmu, or enable VT processing for best ANSI support
• Use monospaced fonts for best alignment of box-drawing characters
• Emoji width can vary by terminal; table/banner widths are based on naive visible length

Additional Resources

This library help with rendering basic terminal UIs with styles, colors, and cursor control. For more complex TUIs and interactive apps, you may use:

• Parsing options and flags:
  • For simpler apps, $argv and getopt() should be sufficient
  • For more complex apps, ulrichsg/getopt-php can be used
• Interactive menu: php-school/cli-menu
• Desktop Notification: JoliNotif

What if I need a full-featured CLI framework?

In case you are planning for a multi-command, complex app that requires guided structure and organization, you may check:

• Symfony Console Component
• Laravel Zero
• MiniCLI

Contributing

Contributions are welcome! Please:

1. Fork and clone the repo
2. Create a feature branch: git checkout -b feat/your-thing
3. Install dev deps: composer install
4. Run tests: composer test
5. Follow PSR‑12 and keep changes focused
6. Open a PR with a clear description and before/after context

If you change public APIs, update examples and this README. Small, focused PRs are easier to review.

Roadmap (Ideas)

• ANSI-aware padding/truncation and text alignment helpers
• Color themes/palettes and named styles
• Table cell alignment and per-column styling
• Minimal TUI widgets (prompt list, select, progress spinner lines)

Versioning & License

• Versioned with SemVer (0.x may include minor BC tweaks)
• Licensed under the MIT License — see LICENSE

---

Made with ❤️ for terminal builders. If you ship something with AnsiKit, I’d love to hear about it!