andyduke/console-keyboard

Cross-platform reading of keyboard events in the terminal.

v1.1.0 2023-09-20 11:25 UTC

Requires

• php: >=7.4.0

BSD-3-Clause

• Andy Chentsov

• cli
• keyboard
• keys
• key press

README

Cross-platform reading of keyboard events in the terminal.

Makes it possible to process key presses in the terminal (including arrow keys, escape, enter, etc.) in Linux, Windows, MacOS.

Attention: only works with PHP 7.4 and above, and uses FFI on Windows.

Usage

First, you need to create the Keyboard class using the static create() method, which will create the desired version of the class for the current platform:

$k = Keyboard::create();

Then you need to use a foreach loop to read the incoming keystrokes:

foreach($k->read() as $key) {

}

You don't have to setup console modes to hide the output of the keys pressed - the Keyboard class does this automatically when the loop starts and restores the console mode when exiting the loop.

Attention: Pressing Ctrl-C interrupts the reading cycle.

Inside the loop you do the processing of each key press, for example displaying the name of each key pressed:

$k = Keyboard::create();
foreach($k->read() as $key) {
  echo $key . PHP_EOL;
}

Inside the loop, you can implement any logic, checking which key is pressed, for example, in the above example you can add an exit from the loop using the q key:

$k = Keyboard::create();
foreach($k->read() as $key) {
  if ($key == 'q') {
    break;
  }

  echo $key . PHP_EOL;
}

For keys such as arrow keys, escape, enter, spacebar, insert, delete, etc., the Keyboard class defines a set of constants that can be used in comparison:

$k = Keyboard::create();
foreach($k->read() as $key) {
  if ($key == 'q' || $key == Keyboard::ESC) {
    break;
  }

  echo $key . PHP_EOL;
}

If you want to get not only the name of the key pressed but also the code (for Linux/MacOS this is ANSI code, for Windows this is scan code), you should use the readKey() method to read keys, instead of read().

The readKey() method returns a Key object containing the key name and code, which are accessible using the getKey() and getRawKey() methods, respectively.

A Key object can be compared to a string, which casts it to a string and returns the name of the key. An example of displaying the names and codes of the keys pressed; the q key exits the reading loop:

$k = Keyboard::create();
foreach($k->readKey() as $key) {
  if ($key == 'q') {
    break;
  }

  echo $key->getKey() . ' (' . $key->getRawKey() . ')' . PHP_EOL;
}

Key Constants

Why Generator?

The read() and readKey() methods return a generator, so you must use a foreach loop or another way of working with iterators to read keyboard input.

This is implemented this way because it allows the Keyboard class to automatically setup console modes at the beginning of reading console input and restore console modes after the end of the reading cycle.

License

This project is licensed under the terms of the BSD 3-Clause license.