| 1 |
# clue/reactphp-term |
| 2 |
|
| 3 |
[](https://github.com/clue/reactphp-term/actions) |
| 4 |
[](https://packagist.org/packages/clue/term-react) |
| 5 |
|
| 6 |
Streaming terminal emulator, built on top of [ReactPHP](https://reactphp.org/). |
| 7 |
|
| 8 |
**Table of Contents** |
| 9 |
|
| 10 |
* [Support us](#support-us) |
| 11 |
* [Usage](#usage) |
| 12 |
* [ControlCodeParser](#controlcodeparser) |
| 13 |
* [Install](#install) |
| 14 |
* [Tests](#tests) |
| 15 |
* [License](#license) |
| 16 |
* [More](#more) |
| 17 |
|
| 18 |
## Support us |
| 19 |
|
| 20 |
We invest a lot of time developing, maintaining and updating our awesome |
| 21 |
open-source projects. You can help us sustain this high-quality of our work by |
| 22 |
[becoming a sponsor on GitHub](https://github.com/sponsors/clue). Sponsors get |
| 23 |
numerous benefits in return, see our [sponsoring page](https://github.com/sponsors/clue) |
| 24 |
for details. |
| 25 |
|
| 26 |
Let's take these projects to the next level together! 🚀 |
| 27 |
|
| 28 |
## Usage |
| 29 |
|
| 30 |
### ControlCodeParser |
| 31 |
|
| 32 |
The `ControlCodeParser(ReadableStreamInterface $input)` class can be used to |
| 33 |
parse any control code byte sequences (ANSI / VT100) when reading from an input stream and it |
| 34 |
only returns its plain data stream. |
| 35 |
It wraps a given `ReadableStreamInterface` and exposes its plain data through |
| 36 |
the same interface. |
| 37 |
|
| 38 |
```php |
| 39 |
$stdin = new React\Stream\ReadableResourceStream(STDIN); |
| 40 |
|
| 41 |
$stream = new ControlCodeParser($stdin); |
| 42 |
|
| 43 |
$stream->on('data', function ($chunk) { |
| 44 |
var_dump($chunk); |
| 45 |
}); |
| 46 |
``` |
| 47 |
|
| 48 |
As such, you can be sure the resulting `data` events never include any control |
| 49 |
code byte sequences and it can be processed like a normal plain data stream. |
| 50 |
|
| 51 |
React's streams emit chunks of data strings and make no assumption about any |
| 52 |
byte sequences. |
| 53 |
These chunks do not necessarily represent complete control code byte sequences, |
| 54 |
as a sequence may be broken up into multiple chunks. |
| 55 |
This class reassembles these sequences by buffering incomplete ones. |
| 56 |
|
| 57 |
The following [C1 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C1_set) |
| 58 |
are supported as defined in [ISO/IEC 2022](https://en.wikipedia.org/wiki/ISO/IEC_2022): |
| 59 |
|
| 60 |
* [CSI (Control Sequence Introducer)](https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes) |
| 61 |
is one of the most common forms of control code sequences. |
| 62 |
For example, CSI is used to print colored console output, also known as |
| 63 |
"ANSI color codes" or the more technical term |
| 64 |
[SGR (Select Graphic Rendition)](https://en.wikipedia.org/wiki/ANSI_escape_code#graphics). |
| 65 |
CSI codes also appear on `STDIN`, for example when the user hits special keys, |
| 66 |
such as the cursor, `HOME`, `END` etc. keys. |
| 67 |
|
| 68 |
* OSC (Operating System Command) |
| 69 |
is another common form of control code sequences. |
| 70 |
For example, OSC is used to change the window title or window icon. |
| 71 |
|
| 72 |
* APC (Application Program-Control) |
| 73 |
|
| 74 |
* DPS (Device-Control string) |
| 75 |
|
| 76 |
* PM (Privacy Message) |
| 77 |
|
| 78 |
Each code sequence gets emitted with a dedicated event with its raw byte sequence: |
| 79 |
|
| 80 |
```php |
| 81 |
$stream->on('csi', function ($sequence) { |
| 82 |
if ($sequence === "\x1B[A") { |
| 83 |
echo 'cursor UP pressed'; |
| 84 |
} else if ($sequence === "\x1B[B") { |
| 85 |
echo 'cursor DOWN pressed'; |
| 86 |
} |
| 87 |
}); |
| 88 |
|
| 89 |
$stream->on('osc', function ($sequence) { … }); |
| 90 |
$stream->on('apc', function ($sequence) { … }); |
| 91 |
$stream->on('dps', function ($sequence) { … }); |
| 92 |
$stream->on('pm', function ($sequence) { … }); |
| 93 |
``` |
| 94 |
|
| 95 |
Other lesser known [C1 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C1_set) |
| 96 |
not listed above are supported by just emitting their 2-byte sequence. |
| 97 |
Each generic C1 code gets emitted as an `c1` event with its raw 2-byte sequence: |
| 98 |
|
| 99 |
```php |
| 100 |
$stream->on('c1', function ($sequence) { … }); |
| 101 |
``` |
| 102 |
|
| 103 |
All other [C0 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C0_.28ASCII_and_derivatives.29), |
| 104 |
also known as [ASCII control codes](https://en.wikipedia.org/wiki/ASCII#ASCII_control_code_chart), |
| 105 |
are supported by just emitting their single-byte value. |
| 106 |
Each generic C0 code gets emitted as an `c0` event with its raw single-byte value: |
| 107 |
|
| 108 |
```php |
| 109 |
$stream->on('c0', function ($code) { |
| 110 |
if ($code === "\n") { |
| 111 |
echo 'ENTER pressed'; |
| 112 |
} |
| 113 |
}); |
| 114 |
``` |
| 115 |
|
| 116 |
## Install |
| 117 |
|
| 118 |
The recommended way to install this library is [through Composer](https://getcomposer.org/). |
| 119 |
[New to Composer?](https://getcomposer.org/doc/00-intro.md) |
| 120 |
|
| 121 |
This project follows [SemVer](https://semver.org/). |
| 122 |
This will install the latest supported version: |
| 123 |
|
| 124 |
```bash |
| 125 |
composer require clue/term-react:^1.4 |
| 126 |
``` |
| 127 |
|
| 128 |
See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. |
| 129 |
|
| 130 |
This project aims to run on any platform and thus does not require any PHP |
| 131 |
extensions and supports running on legacy PHP 5.3 through current PHP 8+ and |
| 132 |
HHVM. |
| 133 |
It's *highly recommended to use the latest supported PHP version* for this project. |
| 134 |
|
| 135 |
## Tests |
| 136 |
|
| 137 |
To run the test suite, you first need to clone this repo and then install all |
| 138 |
dependencies [through Composer](https://getcomposer.org/): |
| 139 |
|
| 140 |
```bash |
| 141 |
composer install |
| 142 |
``` |
| 143 |
|
| 144 |
To run the test suite, go to the project root and run: |
| 145 |
|
| 146 |
```bash |
| 147 |
vendor/bin/phpunit |
| 148 |
``` |
| 149 |
|
| 150 |
## License |
| 151 |
|
| 152 |
This project is released under the permissive [MIT license](LICENSE). |
| 153 |
|
| 154 |
> Did you know that I offer custom development services and issuing invoices for |
| 155 |
sponsorships of releases and for contributions? Contact me (@clue) for details. |
| 156 |
|
| 157 |
## More |
| 158 |
|
| 159 |
* If you want to learn more about processing streams of data, refer to the documentation of |
| 160 |
the underlying [react/stream](https://github.com/reactphp/stream) component. |
| 161 |
|
| 162 |
* If you want to process UTF-8 encoded console input, you may |
| 163 |
want to use [clue/reactphp-utf8](https://github.com/clue/reactphp-utf8) on the resulting |
| 164 |
plain data stream. |
| 165 |
|
| 166 |
* If you want to to display or inspect the control codes, you may |
| 167 |
want to use either [clue/hexdump](https://github.com/clue/php-hexdump) or |
| 168 |
[clue/caret-notation](https://github.com/clue/php-caret-notation) on the emitted |
| 169 |
control byte sequences. |
| 170 |
|
| 171 |
* If you want to process standard input and output (STDIN and STDOUT) from a TTY, you may |
| 172 |
want to use [clue/reactphp-stdio](https://github.com/clue/reactphp-stdio) instead of |
| 173 |
using this low-level library. |