ANSI sequence generator library for PHP

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