README

Simple CLI interactions for PHP

Terminus provides everything you need to build highly interactive, beautiful CLI processes.

Get news and updates on the DecodeLabs blog.

Installation

composer require decodelabs/terminus

Usage

Writing output

Write standard text to output:

use DecodeLabs\Terminus as Cli;

Cli::write('Normal text'); // no newline
Cli::writeLine(' - end of line'); // with newline

Error output works the same way, with Error in the method name:

use DecodeLabs\Terminus as Cli;

Cli::writeError('Error text'); // no newline
Cli::writeErrorLine(' - end of line'); // with newline

Reading input

Read input from the user: Note, PHP by default buffers the input stream so input requires return to be pressed before it can be read.

use DecodeLabs\Terminus as Cli;

$data = Cli::read(3); // Read 3 bytes
$line = Cli::readLine();

If the connected terminal supports stty (most Unix emulators), buffering can be turned off for instant input:

use DecodeLabs\Terminus as Cli;

Cli::toggleInputBuffer(false);
Cli::writeLine('Yes or no?')
$char = Cli::read(1); // y or n
Cli::toggleInputBuffer(true);

More on extended ANSI and stty support below.

Colors and styles

If the connected terminal can support ANSI codes can be styled easily using a handy shortcut on the facade:

use DecodeLabs\Terminus as Cli;

Cli::{'blue'}('This is blue ');
Cli::{'yellow'}('This is yellow ');
Cli::{'red|green|underline'}(' This is red on green, underlined');
Cli::{'+'}('This starts on a new line');
Cli::{'.'}('- this ends on a new line');
Cli::{'>>'}('This is tabbed, twice!');
Cli::{'<'}(' - this backspaces the last character');
Cli::writeLine();
Cli::{'++>..:146|#CCC|bold|underline'}('A whole mix of parameters');

Support for ANSI codes can be checked with:

use DecodeLabs\Terminus as Cli;

if(Cli::isAnsi()) {
    // do stuff
}

The format of the style prefix is as follows:

<modifiers>foreground?|background?|option1?|option2?...

Modifiers are applied as many times as they appear sequentially.

• Modifiers:
  • ^ Clear line(s) above
  • + Add lines before
  • . Add lines after
  • > Add tabs before
  • < Backspace previous output
  • ! Considered an error
  • !! Not considered an error
• Foreground / background
  • black (ANSI)
  • red (ANSI)
  • green (ANSI)
  • yellow (ANSI)
  • blue (ANSI)
  • magenta (ANSI)
  • cyan (ANSI)
  • white (ANSI)
  • reset (ANSI)
  • brightBlack (ANSI)
  • brightRed (ANSI)
  • brightGreen (ANSI)
  • brightYellow (ANSI)
  • brightBlue (ANSI)
  • brightMagenta (ANSI)
  • brightCyan (ANSI)
  • brightWhite (ANSI)
  • :0 to :255 8bit color code
  • #000000 to #FFFFFF 24bit hex color
• Options
  • bold
  • dim
  • italic
  • underline
  • blink
  • strobe
  • reverse
  • private
  • strike

Note, some options are not or only partially supported on many terminal emulators.

Line control

Directly control lines and the cursor: All of the below methods allow passing a numeric value to control the number of times it should be applied.

use DecodeLabs\Terminus as Cli;

Cli::newLine(); // Write to a new line
Cli::newLine(5); // Write 5 new lines
Cli::deleteLine(); // Delete the previous line
Cli::clearLine(); // Clear the current line
Cli::clearLineBefore(); // Clear the current line from cursor to start
Cli::clearLineAfter(); // Clear the current line from cursor to end
Cli::backspace(); // Clear the previous character
Cli::tab(); // Write \t to output

Cli::cursorUp(); // Move cursor up vertically
Cli::cursorLineUp(); // Move cursor up to start of previous line
Cli::cursorDown(); // Move cursor down vertically
Cli::cursorLineDown(); // Move cursor down to start of next line
Cli::cursorLeft(); // Move cursor left
Cli::cursorRight(); // Move cursor right

Cli::setCursor(5); // Set cursor horizontally to index 5
Cli::setCursorLine(30, 10); // Set absolute cursor position

[$line, $pos] = Cli::getCursor(); // Attempt to get absolute cursor position
$pos = Cli::getCursorH(); // Attempt to get horizontal cursor position
$line = Cli::getCursorV(); // Attempt to get vertical cursor position

Cli::saveCursor(); // Store cursor position in terminal memory
Cli::restoreCursor(); // Attempt to restore cursor position from terminal memory

$width = Cli::getWidth(); // Get line width of terminal
$height = Cli::getHeight(); // Get line height of terminal

stty

Some extended functionality is dependent on stty being available (most Unix emulators).

use DecodeLabs\Terminus as Cli;

Cli::toggleInputEcho(false); // Hide input characters
Cli::toggleInputBuffer(false); // Don't wait on return key for input

stty can be controlled with the following methods:

use DecodeLabs\Terminus as Cli;

if(Cli::hasStty()) {
    $snapshot = Cli::snapshotStty(); // Take a snapshot of current settings
    Cli::toggleInputEcho(false);
    // do some stuff

    Cli::restoreStty($snapshot); // Restore settings
    // or
    Cli::resetStty(); // Reset to original settings at the start of execution
}

Widgets

Simplify common use cases with built in widgets:

Question

use DecodeLabs\Terminus as Cli;

$answer = Cli::newQuestion('How are you?')
    ->setOptions('Great', 'Fine', 'OK')
    ->setDefaultValue('great')
    ->prompt();


// Or direct..
$answer = Cli::ask('How are you?', 'great');

Cli::{'..green'}('You are: '.$answer);

Password

$password = Cli::newPasswordQuestion('Now enter a password...')
    ->setRequired(true)
    ->setRepeat(true)
    ->prompt();

// Or direct
$password = Cli::askPassword('Now enter a password...', true, true);

Cli::{'..green'}('Your password is: '.$password);

Confirmation

use DecodeLabs\Terminus as Cli;

if (Cli::confirm('Do you like green?', true)) {
    Cli::{'..brightGreen'}('Awesome!');
} else {
    Cli::{'..brightRed'}('Boo!');
}

Spinner

use DecodeLabs\Terminus as Cli;

Cli::{'.'}('Progress spinner: ');
$spinner = Cli::newSpinner();

for ($i = 0; $i < 60; $i++) {
    usleep(20000);
    $spinner->advance();
}

$spinner->complete('Done!');

Progress bar

use DecodeLabs\Terminus as Cli;

Cli::{'.'}('Progress bar: ');
$spinner = Cli::newProgressBar(10, 50);

for ($i = 0; $i < 80; $i++) {
    usleep(20000);
    $spinner->advance(($i / 2) + 11);
}

$spinner->complete();

Use Terminus as a PSR Logger

use DecodeLabs\Terminus as Cli;

Cli::debug('This is a debug');
Cli::info('This is an info message');
Cli::notice('This is a notice');
Cli::success('You\'ve done a success, well done!');
Cli::warning('This is a warning');
Cli::error('Hold tight, we have an error');
Cli::critical('This is CRITICAL');
Cli::alert('alert alert alert');
Cli::emergency('Oh no this is an emergency!');

Argument parsing

Quickly parse input arguments from the request into the session:

use DecodeLabs\Terminus as Cli;

Cli::$command
    ->setHelp('Test out Terminus functionality')
    ->addArgument('action', 'Unnamed action argument')
    ->addArgument('?-test|t=Test arg', 'Named test argument with default value');

$action = Cli::$command['action'];
$test = Cli::$command['test'];

Session

Terminus will by default create a standard session communicating via PHP's STDIN, STDOUT and STDERR streams, with arguments from $_SERVER['argv'].

You can however customise the session by creating your own and setting it via the main Terminus frontage. See Deliverance Broker for more information about controlling IO streams.

use DecodeLabs\Deliverance;
use DecodeLabs\Terminus as Cli;

$session = Cli::newSession(
    Cli::newRequest(['list', 'of', 'argv', 'params']),

    // The Io Broker is optional, defaults to best fit
    Deliverance::newIoBroker()
        ->addInputProvider($inputStream)
        ->addOutputReceiver($outputStream)
        ->addErrorReceiver($errorStream)
);

Cli::setSession($session);

Veneer

Terminus uses Veneer to provide a unified frontage under DecodeLabs\Terminus. You can access all the primary functionality via this static frontage without compromising testing and dependency injection.

Licensing

Terminus is licensed under the MIT License. See LICENSE for the full license text.