PHP Classes

PHP CLI Input: Process keys pressed by the user in the shell

Recommend this page to a friend!
  Info   View files View files (4)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2021-11-22 (5 months ago) RSS 2.0 feedNot yet rated by the usersTotal: 247 All time: 7,889 This week: 185Up
Version License PHP version Categories
cli-input 0.4MIT/X Consortium ...5.0PHP 5, Console
Description Author

This class can process keys pressed by the user in the shell.

It can read the characters typed by the user in a command line shell ANSI terminal and return what the user entered.

The class can invoke given callback functions when the user presses certain keys like cursor, escape, return, tab, backspace, delete, or any other character.

The callback functions can perform actions that alter the text entered by the user like for instance performing auto-completion.

Picture of Gaspar
Name: Gaspar <contact>
Classes: 1 package by
Country: Spain Spain
Age: ???
All time rank: 3943105 in Spain Spain
Week rank: 577 Up21 in Spain Spain Up


Its an easy way to insert text in our CLI projects for Linux servers. 
We can move backward and forward, implement completion, insert text
inside a line and some more things making text input more useful.

	1 - Text from STDIN
	2 - Installation
	3 - Using it
	  3.1 - Callbacks
	  3.2 - Other options
	4 - Key reference
	5 - To-do
	6 - Version
	7 - Updated information

1 - Text from STDIN
We can make interactive CLI programs in PHP, where we ask the user
for some information, this way:

	$text = fread(STDIN, 100);

But, the problem is when the user wants to go backward in the console, it
will be detected as a new key and the character combination for the left arrow
will be written on the screen (maybe we can edit the text). But we are used
to BASH/DASH or similar stuff, and maybe we want some more options.

2 - Installation
To start using CLIInput in your projects, just include or require the
file CLIInput.class.php:


	You must copy this file to your project directory, and it can be located 
wherever you want (some lib directory).

3 - Using it
The simple way to start using CLIInput is installing it, creating a 
CLIInput object and then calling the read() method, this way:

	$cli = new CLIInput();
	$text = $cli->read();

But, of course you can customize a bit this call, it accepts some arguments:
  * max length of the text, default to 30
  * callbacks, really useful, explained later. (3.1)
  * other options, to customize a little more (3.2)

We can call the read method like this:

        $cli = new CLIInput();
        $text = $cli->read(100);

To make the texts longer. But be aware it is not compatible yet with multiline
inputs, so we will get a weird result if the input string it too long and it
requires some lines.

3.1 - Callbacks
CLIInput is able to call external functions or methods when an event 
occurs, for example a key press. We may want this interact with our scripts, 
to achieve better results, for example, implement completion to our input, when
the user presses up or down keys (See key reference: 4)

	To use callbacks is really simple, just enter an array as the second 
argument of read(), where it will have as keys the keyboard's key identifier,
and as value, the name of the function we want to call, or an array containing
(object, method), as call_user_func_array() needs. 

The callbacks function will have 3 arguments:
	* current string: Is the string the user have written until this moment.
	* state : Is an array with the state variables:
		- 'pos' : Cursor position
		- 'insert' : Insert state, true if the user can insert text, false
			     if the text will be replaced. As insert key do.
	* options : Special options for the callback (See key reference: 4)

Also the callbacks response must be an array containig the following:
	* string : New string to write
	* pos : Move cursor to new position
	* end : To force exit and return current text
	* insert : The new insert state.

You don't have to include all these keys into the returned array.

For example:


	function completion_up($string, $state, $options)
		return array('string' => strtoupper($string),
			     'pos' => 0);

        $cli = new CLIInput();
        $text = $cli->read(100, array('up' => 'completion_up'));

or we can finish text input without a result (for skipping text fields):


        function escape_key($string, $state, $options)
                return array('string' => '',
                             'end' => true);

        $cli = new CLIInput();
        $text = $cli->read(100, array('escape' => 'escape_key'));


3.2 - Other options
At this moment, other options are related to highlights. This class, can
write some events where the text appears, like when we press the Insert key, the
Escape key or we are deleting in an empty string. This argument is an array than 
can contain these keys:
	* 'messageHighlight' : Enable highlighting. Defaults to true.
	* 'escapeHighlight' : Enable highlighting Escape key. Defaults to true.
	* 'insertHighlight' : Enable highlighting Insert key. Defaults to true.
        * 'emptyHighlight' : Enable empty string highlighting. Defaults to true.
        * 'highlightStyle' : What to write when highlighing event. The default 
			     string is " [ \033[1m%s\033[0m ] " wich shows the
			     event name in bold between brackets.
        * 'highlightTime' : Microseconds the message will be on screen before 
			    deleting it. Defaults to 1000000us = 1 second.
        * 'escapeMessage' : Message to show when Escape event is triggered.
			    Defaults to "ESCAPE".
        * 'insertMessage' : Message to show when Insert event is triggered.
			    Defaults to "INSERT".
        * 'emptyMessage' : Message to show when Empty event is triggered.
			   Defaults to "EMPTY",

If we want to skip callbacks array and give options to the read event, just give
NULL value to callbacks argument.

4 - Key reference
These are the keys used in this class. All names are lowercase. Some are
self explanatory and doesn't have additional options (third arguments in callbacks),
so I won't give more details:

	* tab
	* backspace : options array ('oldPos' => (old cursor position))
	* enter : doesn't trigger an event, just make end=true
	* insert 
	* delete : options array ('oldPos' => (old cursor position),
				  'deletedChar' => (deleted character))
	* up
	* down
	* pgup
	* pgdown
	* left : options array ('oldPos' => (old cursor position))
	* right : options array ('oldPos' => (old cursor position))
	* start : options array ('oldPos' => (old cursor position))
	* end : options array ('oldPos' => (old cursor position))
	* escape
	* character : Any written character. 
		      Options array ('character' => (character written))

5 - To-do
There are always things to do with projects. But I have a little list:

	* Enable use of Ctrl+arrows to locate words
	* Enable use of Ctrl+W to delete words
	* Give callbacks the chance to avoid key action. For example, if we
	  are writing a number, avoid letters
	* Multiline inputs
	* Single key inputs for option menus, or S/N inputs

	* Please feel free to suggest anything you consider useful sending me
	  an e-mail, or leaving a message in the blog.

6 - Version
This is the first revision of the document, (20130821)

	This document belongs to CLIInput version 0.3

7 - Updated information
I will try to keep github updated, but I feel more comfortable publishing
all changes in my projects blog: or explaining some
parts of the code in (in Spanish), so, you may 
find the latest updated information there.

	You can also make bug reports, comments and feature requests in github, 
sending me an e-mail to gaspy [at] totaki [dot] com or writting comments in the blogs.

Thank you, I hope this is useful for you
  Files folder image Files  
File Role Description
Plain text file CLIInput.class.php Class Class source
Accessible without login Plain text file clitest.php Example Example script
Accessible without login Plain text file clitest2.php Example Example script
Accessible without login Plain text file Data Auxiliary data

 Version Control Unique User Downloads Download Rankings  
This week:0
All time:7,889
This week:185Up
User Comments (1)
8 years ago (Rahul Shambharkar)
For more information send a message to info at phpclasses dot org.