clue/reactphp-term

Streaming terminal emulator, built on top of ReactPHP.

Table of Contents

Support us
Usage
- ControlCodeParser
Install
Tests
License
More

Support us

We invest a lot of time developing, maintaining and updating our awesome open-source projects. You can help us sustain this high-quality of our work by becoming a sponsor on GitHub. Sponsors get numerous benefits in return, see our sponsoring page for details.

Let's take these projects to the next level together! 🚀

Usage

ControlCodeParser

The ControlCodeParser(ReadableStreamInterface $input) class can be used to parse any control code byte sequences (ANSI / VT100) when reading from an input stream and it only returns its plain data stream. It wraps a given ReadableStreamInterface and exposes its plain data through the same interface.

$stdin = new React\Stream\ReadableResourceStream(STDIN);

$stream = new ControlCodeParser($stdin);

$stream->on('data', function ($chunk) {
    var_dump($chunk);
});

As such, you can be sure the resulting data events never include any control code byte sequences and it can be processed like a normal plain data stream.

React's streams emit chunks of data strings and make no assumption about any byte sequences. These chunks do not necessarily represent complete control code byte sequences, as a sequence may be broken up into multiple chunks. This class reassembles these sequences by buffering incomplete ones.

The following C1 control codes are supported as defined in ISO/IEC 2022:

CSI (Control Sequence Introducer) is one of the most common forms of control code sequences. For example, CSI is used to print colored console output, also known as "ANSI color codes" or the more technical term SGR (Select Graphic Rendition). CSI codes also appear on STDIN, for example when the user hits special keys, such as the cursor, HOME, END etc. keys.
OSC (Operating System Command) is another common form of control code sequences. For example, OSC is used to change the window title or window icon.
APC (Application Program-Control)
DPS (Device-Control string)
PM (Privacy Message)

Each code sequence gets emitted with a dedicated event with its raw byte sequence:

$stream->on('csi', function ($sequence) {
    if ($sequence === "\x1B[A") {
        echo 'cursor UP pressed';
    } else if ($sequence === "\x1B[B") {
        echo 'cursor DOWN pressed';
    }
});

$stream->on('osc', function ($sequence) { … });
$stream->on('apc', function ($sequence) { … });
$stream->on('dps', function ($sequence) { … });
$stream->on('pm', function ($sequence) { … });

Other lesser known C1 control codes not listed above are supported by just emitting their 2-byte sequence. Each generic C1 code gets emitted as an c1 event with its raw 2-byte sequence:

$stream->on('c1', function ($sequence) { … });

All other C0 control codes, also known as ASCII control codes, are supported by just emitting their single-byte value. Each generic C0 code gets emitted as an c0 event with its raw single-byte value:

$stream->on('c0', function ($code) {
    if ($code === "\n") {
        echo 'ENTER pressed';
    }
});

Install

The recommended way to install this library is through Composer. New to Composer?

This project follows SemVer. This will install the latest supported version:

$ composer require clue/term-react:^1.3

See also the CHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM. It's highly recommended to use PHP 7+ for this project.

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

$ composer install

To run the test suite, go to the project root and run:

$ php vendor/bin/phpunit

License

This project is released under the permissive MIT license.

Did you know that I offer custom development services and issuing invoices for sponsorships of releases and for contributions? Contact me (@clue) for details.

If you want to learn more about processing streams of data, refer to the documentation of the underlying react/stream component.
If you want to process UTF-8 encoded console input, you may want to use clue/reactphp-utf8 on the resulting plain data stream.
If you want to to display or inspect the control codes, you may want to use either clue/hexdump or clue/caret-notation on the emitted control byte sequences.
If you want to process standard input and output (STDIN and STDOUT) from a TTY, you may want to use clue/reactphp-stdio instead of using this low-level library.

bgreenacre/reactphp-term