README

This library will enable you to easily generate ANSI sequence strings in CLI.

The list below are some things you can do with this library.

• Set foreground/background color
• Set font styles (bold/italic)
• Move cursor positions
• Clear the screen
• Get the terminal size

Prerequisites

• PHP 8.1+

Installation

composer require south-pointe/ansi

Example

use SouthPointe\Ansi\Ansi;
use SouthPointe\Ansi\Codes\Color;

// Change foreground text to blue.
echo Ansi::fgColor(Color::Blue);

// Set color by 256-color mode.
echo Ansi::fgColor(Color::code(12));

// Move the cursor back by 2.
echo Ansi::cursorBack(2);

// Add "test" + "\e[0m" (reset style) + "\r" (carriage return) + "\n" (new line)
echo Ansi::line('test');

// Ansi::buffer() will allow you to chain multiple sequences.
echo Ansi::buffer()
    ->bold()
    ->fgColor(Color::Gray)
    ->text('foo bar')
    ->resetStyle()
    ->toString();

// Will send the string to STDOUT (default stream uri)
echo Ansi::stream()
    ->text('to stdout')
    ->flush();

// Will send the string to STDERR
echo Ansi::stream(STDERR)
    ->bgColor(Color::Red)
    ->flush();

// Returns the size of the terminal as ['row' => int, 'column' => int].
echo Ansi::getTerminalSize();

Methods

Ansi

This is the main class you should be using to generate the sequence codes.
All methods in this class are static.

• Ansi::buffer(): Buffer Starts a buffered instance. Used for chaining sequences.
• Ansi::line($text): string Output text, reset style, and move to the new line.
• Ansi::bell(): string Rings the bell.
• Ansi::backspace(): string Moves the cursor back.
• Ansi::tab(): string Moves the cursor by 8 spaces.
• Ansi::lineFeed(): string Moves to the next line and scroll screen up.
• Ansi::carriageReturn(): string Moves cursor to column 0.
• Ansi::cursorUp(int $n = 1): string Moves the cursor up $n rows.
• Ansi::cursorDown(int $n = 1): string Moves the cursor down $n rows.
• Ansi::cursorForward(int $n = 1): string Moves the cursor forward $n cells.
• Ansi::cursorBack(int $n = 1): string Moves the cursor back $n cells.
• Ansi::cursorNextLine(int $n = 1): string Moves cursor to start of line and move down by $n.
• Ansi::cursorPreviousLine(int $n = 1): string Moves cursor to the start of line and move up by $n.
• Ansi::cursorPosition(int $row, int $column): string Moves cursor to the specified position.
• Ansi::eraseScreen(): string Erases the entire screen.
• Ansi::eraseToEndOfScreen(): string Erases from the cursor position to the end of screen.
• Ansi::eraseFromStartOfScreen(): string Erases from the start of screen to the cursor position.
• Ansi::eraseSavedLines(): string Clears the screen and deletes all lines in the scrollback buffer.
• Ansi::eraseLine(): string Erases the entire line. Cursor Position will not change.
• Ansi::eraseToEndOfLine(): string Erases from cursor position to the end of the line.
• Ansi::eraseFromStartOfLine(): string Erases from the start of the line to the cursor position.
• Ansi::scrollUp(int $lines = 1): string Scrolls the screen up by $lines.
• Ansi::scrollDown(int $lines = 1): string Scrolls the screen down by $lines.
• Ansi::resetStyle(): string Resets the style of the output.
• Ansi::bold(bool $toggle = true): string Applies bold styling to succeeding text.
• Ansi::italic(bool $toggle = true): string Applies italic styling to succeeding text.
• Ansi::underline(bool $toggle = true): string Underlines to succeeding text.
• Ansi::blink(bool $toggle = true): string Makes succeeding text blink.
• Ansi::foreground(Color $color): string Applies the given color to the foreground font.
• Ansi::foreground(Color $color): string Applies the given color to the background font.
• Ansi::deviceStatusReport(): string Gives the device status report.
• Ansi::getTerminalSize(): array{ row: int, column: int } Get the terminal size of the current terminal.

Buffer

This class should be instantiated by calling Ansi::buffer().
Buffered class contains all methods in Ansi class except getTerminalSize.

• text(string $text): self Adds text to buffer.
• flush(resource $to): self Flushes all sequences buffered to the given resource.
• clear(): self Clears all sequences stored in the buffer.
• toString(): string Coverts all buffered sequences to string.

Color

Enum that contains shortcut names for 8-bit colors.
Check out the actual class for all the names.

• Color::code(int $code): self Gets the color by number.

License

This is an open-sourced software licensed under the MIT License.

References

• ANSI escape code - Wikipedia
• ANSI Escape Codes - Gist
• Chapter 6. ANSI Escape Sequences: Colours and Cursor Movement - Bash Prompt HOWTO