README

Low-level terminal control library heavily inspired by crossterm.

Installation
Requiremens
Usage
Testing
Contributing

Installation

$ composer require php-tui/term

Requirements

I have only tested this library on Linux. It currently requires stty to enable the raw mode and detect the current window size. It should work on MacOS and WSL.

Native Windows is currently not supported as I cannot test on Windows, the architecture should support Windows however, so if you'd like to make a start look at crossterm for inspiration and start a PR.

Usage

Actions

You can send data to the terminal using actions.

<?php

$terminal = Terminal::new();

// queue an action
$terminal->queue(Actions::printString('Hello World'));

// flush the queue to the terminal
$terminal->flush();

// or you can execute it directly
$terminal->execute(Actions::printString('Hello World'));

All actions are made available via. the Actions factory:

Events

Term provides user events:

while (true) {
    while ($event = $terminal->events()->next()) {
        if ($event instanceof CodedKeyEvent) {
            if ($event->code === KeyCode::Esc) {
                // escape pressed
            }
        }
        if ($event instanceof CharKeyEvent) {
            if ($event->char === 'c' && $event->modifiers === KeyModifiers::CONTROL) {
                // ctrl-c pressed
            }
        }
    }
    usleep(10000);
}

The events are as follows:

PhpTui\Term\Event\CharKeyEvent: Standard character key
PhpTui\Term\Event\CodedKeyEvent: Special key, e.g. escape, control, page up, arrow down, etc
PhpTui\Term\Event\CursorPositionEvent: as a response to Actions::requestCursorPosition.
PhpTui\Term\Event\FocusEvent: for when focus has been gained or lost
PhpTui\Term\Event\FunctionKeyEvent: when a function key is pressed
PhpTui\Term\Event\MouseEvent: When the Actions::enableMouseCapture has been called, provides mouse event information.
PhpTui\Term\Event\TerminalResizedEvent: The terminal was resized.

Terminal Size

You can request the terminal size:

<?php

$terminal = Terminal::new();

$size = $terminal->info(Size::class);
if (null !== $size) {
    echo $size->__toString() . "\n";
} else {
    echo 'Could not determine terminal size'."\n";
}

Raw Mode

Raw mode disables all the default terminal behaviors and is what you typically want to enable when you want a fully interactive terminal.

<?php

$terminal = Terminal::new();
$terminal->enableRawMode();
$terminal->disableRawMode();

Always be sure to disable raw mode as it will leave the terminal in a barely useable state otherwise!

Parsing

In addition Term provides a parser which can parse any escape code emitted by the actions.

This is useful if you want to capture the output from a terminal application and convert it to a set of Actions which can then be redrawn in another medium (e.g. plain text or HTML).

use PhpTui\Term\AnsiParser;
$actions = AnsiParser::parseString($rawAnsiOutput, true);

Testing

The Terminal has testable versions of all it's dependencies:

<?php

$painter = ArrayPainter::new();
$eventProvider = ArrayEventProvider::fromEvents(
    CharKeyEvent::new('c')
);
$infoProvider = ClosureInformationProvider::new(
    function (string $classFqn): TerminalInformation {
        return new class implements TerminalInformation {};
    }
);
$rawMode = new TestRawMode();

$term = Terminal::new(
    painter: $painter,
    infoProvider: $infoProvider,
    eventProvider: $eventProvider,
    rawMode: $rawMode
);
$term->execute(
    Actions::printString('Hello World'),
    Actions::setTitle('Terminal Title'),
);

echo implode("\n", array_map(
    fn (Action $action) => $action->__toString(),
    $painter->actions()
)). "\n";

See the example testable.php in examples/.

Contributing

PRs for missing functionalities and improvements are charactr.

php-tui / term

Maintainers

Details