tty.php

<?php

/**
 * Get or set the echo mode of a console
 *
 * - When echo is enabled, keyboard input events are automatically copied to the output buffer and displayed.
 * - Otherwise, keyboard input events are not displayed automatically - the application is responsible for updating the output
 *   buffer to display the result.
 *
 * Echo mode is typically enabled by default. The most common use for disabling echo is when collecting sensitive data (such as a
 * password) from a user, which should not be displayed. Echo should also be disabled when emitting VT100 "query" control
 * sequences, to prevent the response sequence being printed to screen.
 *
 * @param  resource  $stream Stream resource representing the input stream of a console
 * @param  bool|null $enable The new echo mode or NULL to leave unchanged
 * @return bool              The original echo mode
 * @throws TypeError         When $stream is not a valid console input stream resource
 * @throws Error             When an operation to get or set the mode of the stream fails
 */
function stream_tty_input_echo($stream, bool $enable = null): bool
{
    /*
         Windows:
           - Throw if $stream is not a console input handle
             - Both GetConsoleMode() and PeekConsoleInput() must succeed for a handle to be considered valid
           - Set return value to (mode & ENABLE_ECHO_INPUT) == ENABLE_ECHO_INPUT
           - If $enable !== null, invoke SetConsoleMode() to set/clear ENABLE_ECHO_INPUT flag
             - Throw if SetConsoleMode() call returns failure

         POSIX:
           - Throw if $stream is not a tty
           - Invoke tcgetattr()
             - Throw if tcgetattr() call returns failure
             - Set return value to (termios_p->c_lflag & ECHO) == ECHO
           - If $enable !== null, invoke tcsetattr() to set/clear ECHO flag
             - Throw if tcsetattr() call returns failure
             - The optional_actions argument uses the TCSANOW value
             - $enable === false also clears ECHONL flag to reduce scope for unexpected behaviour in the 99% case - programs
               requiring more granular control should use stream_tty_mode()
     */
}

/**
 * Get or set the canonical mode of a console
 *
 * - In canonical mode, input is sent to the program line-by-line - data is only made available on the input stream when EOL/EOF
 *   is encountered, typically when a user presses the return/enter key. Input lines may be edited, edit actions are processed by
 *   the console and the final result is sent to the input stream.
 * - When canonical mode is disabled, input is sent directly to the program on the fly. Edit actions (e.g. backspace, delete or
 *   cursor navigation) are not interpreted and must be handled by the program.
 *
 * Canonical mode is typically enabled by default, and should only be disabled when a program needs to respond to user actions
 * immediately. Common use cases are "press any key to continue" interactions or responding to navigation key strokes. Canonical
 * mode should also be disabled when emitting VT100 "query" control sequences, as the response sequence is not terminated with
 * an EOL character.
 *
 * @param  resource  $stream Stream resource representing the input stream of a console
 * @param  bool|null $enable The new canonical mode or NULL to leave unchanged
 * @return bool              The original canonical mode
 * @throws TypeError         When $stream is not a valid console input stream resource
 * @throws Error             When an operation to get or set the mode of the stream fails
 */
function stream_tty_input_canonical($stream, bool $enable = null): bool
{
    /*
         Windows:
           - Throw if $stream is not a console input handle
             - Both GetConsoleMode() and PeekConsoleInput() must succeed for a handle to be considered valid
           - Set return value to (mode & ENABLE_LINE_INPUT) == 0
           - If $enable !== null, invoke SetConsoleMode() to set/clear ENABLE_LINE_INPUT flag
             - Throw error if SetConsoleMode() call returns failure

         POSIX:
           - Throw error if $stream is not tty
           - Invoke tcgetattr()
             - Throw if tcgetattr() call returns failure
             - Set return value to (termios_p->c_lflag &  ICANON) ==  ICANON
           - If $enable !== null, invoke tcsetattr() to set/clear ICANON flag
             - Throw error if tcsetattr() call returns failure
             - $enable === true also sets MIN=1,TIME=0 in c_cc to ensure that reads are blocking by default
     */
}

/**
 * Get or set the raw mode options of a console
 *
 * This function provides direct access to the underlying system API for manipulating the operating mode of a console. Data is
 * exposed as an associative array representing the `termios` structure, with the following keys:
 *
 * [input]   - Integer mapped to the `c_iflag` member. On Windows this only has a value for input streams, otherwise NULL.
 * [output]  - Integer mapped to the `c_oflag` member. On Windows this only has a value for output streams, otherwise NULL.
 * [control] - Integer mapped to the `c_cflag` member. On Windows this is always NULL.
 * [local]   - Integer mapped to the `c_lflag` member. On Windows this is always NULL.
 * [chars]   - Array of strings mapped to the `c_cc` member. On Windows this is always NULL.
 *
 * When setting the mode, each key which exists in the supplied data with a non-null value is used to define the corresponding
 * member of the `termios` struct. Any key which is missing or null is ignored and the current value is retained. Similarly, any
 * key which not defined in the `chars` array is not altered. The current strict_types mode determines the casting behaviour for
 * values within the data. If a string in the `chars` array is not exactly 1 byte, it is treated a type error.
 *
 * On Windows, only the `input` and `output` keys have meaning, depending on whether the handle is an input or output stream.
 * Only the applicable key is processed when setting the mode, all other keys are ignored.
 *
 * @param  resource   $stream Stream resource representing a console
 * @param  array|null $mode   The new mode or NULL to leave unchanged
 * @return array              The original mode
 * @throws TypeError          When $stream is not a valid console input or output stream resource
 * @throws Error              When an operation to get or set the mode of the stream fails
 */
function stream_tty_mode($stream, array $mode = null): array
{
    /*
         Windows:
           - Throw if $stream is not a console handle
             - GetConsoleMode() must succeed for a handle to be considered valid
             - PeekConsoleInput() is used to determine whether the handle is an input or output stream
           - Populate the applicable key of the result array with current mode, all other keys are set to NULL
           - If $mode !== null and the applicable key is defined, invoke SetConsoleMode()
             - Throw error if SetConsoleMode() call returns failure

         POSIX:
           - Throw error if $stream is not tty
           - Invoke tcgetattr()
             - Throw if tcgetattr() call returns failure
             - Populate result array from resulting `termios` struct
           - If $mode !== null, invoke tcsetattr()
             - Throw error if tcsetattr() call returns failure
     */
}