README

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 and utilities.

Works on 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.

Why Choose AnsiKit?

Zero dependencies, PSR-12 with strict types, and a beautiful chainable API. Perfect for small CLI tools, deployment scripts, or any terminal-based app where you need style without the weight.

Features

🎨 Text Styling

Standard 8/16 colors, 256-color palette, and truecolor (RGB, 24-bit)
Bold, dim, italic, underline, inverse, hidden, strike-through styles
Easy reset and chaining

📊 UI Components

Table - Beautiful tables with borders and alignment
Banner - Eye-catching banners for messages
Progressbar - Progress tracking with customizable styles
Spinner - Animated spinners for loading states
Choice - Interactive selection prompts
Panel - Flexible container layouts (vertical/horizontal) with borders and dividers
PanelBlock - Individual content blocks that can be nested or standalone

⌨️ Input & Interactivity

Input helpers - Line, multiline, and confirm prompts
Keypress detection - Listen for arrow keys, ENTER, ESC, TAB, modifiers, and more

🎯 Cursor Control

Move cursor to any position
Save/restore cursor state
Show/hide cursor
Alternate screen buffer support

🛠️ Utilities

ANSI-aware string length and stripping
Memory writer for testing
Tab title and bell helpers

See It In Action

php examples/showcase.php

Quick Start

composer require ajaxray/ansikit

<?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]);

Documentation

Core API

AnsiTerminal - Styles, colors, cursor control

Components

Table - Data tables with borders
Banner - Message banners
Progressbar - Progress tracking
Spinner - Loading animations
Choice - Interactive selection
Panel - Container layouts with borders and dividers
PanelBlock - Nested or standalone content blocks

Helpers

Input - User input helpers
Keypress - Keyboard event handling
Str - ANSI-aware string utilities
Util - Terminal helpers

More Examples

php examples/showcase.php   # All components demo
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
php examples/keypress.php    # Interactive key handling demo
php examples/keypress-advanced.php # Advanced key sequences
php examples/util.php        # Tab title + bell helpers
php examples/panel.php       # Panel and PanelBlock demo
php examples/nested_panel.php # Nested Panel and PanelBlock demo

Compatibility

PHP: >= 8.2
Terminals: macOS/Linux native, Windows 10+ with Windows Terminal/ConEmu
Fonts: Monospaced fonts recommended for best alignment

On Windows, ensure VT processing is enabled for ANSI sequences.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE

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

ajaxray / ansikit

Maintainers

Details