Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg

PHP : Function Reference : GNU Readline

GNU Readline


The readline functions implement an interface to the GNU Readline library. These are functions that provide editable command lines. An example being the way Bash allows you to use the arrow keys to insert characters or scroll through command history. Because of the interactive nature of this library, it will be of little use for writing Web applications, but may be useful when writing scripts used from a command line.


This extension is not available on Windows platforms.


To use the readline functions, you need to install libreadline. You can find libreadline on the home page of the GNU Readline project, at it's maintained by chet ramey, who's also the author of bash.

you can also use these functions with the libedit library, a non-gpl replacement for the readline library. the libedit library is bsd licensed and available for download from


To use these functions you must compile the CGI or CLI version of PHP with readline support. You need to configure PHP --with-readline[=DIR]. In order you want to use the libedit readline replacement, configure PHP --with-libedit[=DIR].

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

This extension has no constants defined.

Table of Contents

readline_add_history — Adds a line to the history
readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
readline_clear_history — Clears the history
readline_completion_function — Registers a completion function
readline_info — Gets/sets various internal readline variables
readline_list_history — Lists the history
readline_on_new_line — Inform readline that the cursor has moved to a new line
readline_read_history — Reads the history
readline_redisplay — Redraws the display
readline_write_history — Writes the history
readline — Reads a line

Code Examples / Notes » ref.readline

14-apr-2002 03:17

[Ed. note: you can use fopen("php://stdin", "w") to achieve the same thing, works on both Windows and Unix)]
I wanted to get console input in a PHP script running on windows, so I made a little hack, which is so simple, it is clearly public domain.  What I did was write a C++ program to get a line, then output it.  Then all that is needed is to exec() that program and capture the output - readline() for windows.  The C++ source is as follows:
#include <iostream.h>
#include <string>
void main()
   string input;
   cin >> input;
   cout << input;
It works wonderfully for my purposes, since I love the PHP language and want to have console input.
Justin Henck


You can open /dev/tty on unix systems or \con in windows, with ob_implicit_flush(true) to write output unbuffered.  Works like a charm :-)
#!/usr/local/bin/php -q
class prompt {
 var $tty;
 function prompt() {
   if (substr(PHP_OS, 0, 3) == "WIN") {
     $this->tty = fOpen("\con", "rb");
   } else {
     if (!($this->tty = fOpen("/dev/tty", "r"))) {
       $this->tty = fOpen("php://stdin", "r");
 function get($string, $length = 1024) {
   echo $string;
   $result = trim(fGets($this->tty, $length));
   echo "\n";
   return $result;
echo "Enter something or 'exit' to quit\n";
do {
 $cmdline = new prompt();
 $buffer = $cmdline->get("Something: ");
 echo "You said: $buffer\n";
} while ($buffer !== "exit");
echo "Goodbye\n";


To get all arguments passed to a batch file in one variable
rather than using %1 %2 %3 etc;
if "%1" == "" goto DONE
set args=%args% %1
goto LOOP
@c:\\php\\cli\\php.exe script.php %args%
set args=


There is a simpler way to do a multiline read than above:
function multiline() {
   while(($in = readline("")) != ".")
       $story .= ($PHP_OS == "WINNT") ? "\r\n".$in :
   return $story;


Some Tricks with the PHP readline Modus


Readline only reads the window size on startup or on SIGWINCH.  This means if the window is resized when not in a readline() call, the next call will have odd behavior due to confusion about the window size.
The work-around is to force Readline to re-read the window size by sending it SIGWINCH.  This is accomplished using the async interface, which installs the signal handler but returns control to PHP.
The following function is a drop-in replacement for readline(), but re-reads the window size every time:
   function xreadline($prompt)
       global $xreadline, $xreadline_line;
       $code = '$GLOBALS["xreadline"] = false;' .
               '$GLOBALS["xreadline_line"] = $line;' .
       $cb = create_function('$line', $code);
       readline_callback_handler_install($prompt, $cb);
       $signal = defined("SIGWINCH") ? SIGWINCH : 28;
       posix_kill(posix_getpid(), $signal);
       $xreadline = true;
       while ($xreadline)
       return is_null($xreadline_line) ? false : $xreadline_line;


re to: ds at NOSPAM dot undesigned dot org dot za
cool program! note when trying to exec() something:
in the while loop you need to reset exec() returns or you will get all results of all executions (on my my windows and or cygwin :-(
// your class prompt()
echo "Enter something or 'exit' to quit\n";
do {
$cmdline = new prompt();
$buffer = $cmdline->get('shell command: ');
// init/ reset first!
$data = null;
$return = null;
// now start:
echo "You said: $buffer\n";
if (!empty($buffer)) {
$x = exec($buffer, $data, $return);
} while ($buffer !== "exit");
echo "Goodbye\n";


Here's an example simple readline-like way to input from command line on windows - the single line is from, the multiline is something I added...
function read () {
# 4092 max on win32 fopen
$fp=fopen("php://stdin", "r");
# strip newline
(PHP_OS == "WINNT") ? ($read = str_replace("\r\n", "", $in)) : ($read = str_replace("\n", "", $in));
return $read;
function multilineread () {
do {
$in = read();
# test exit
if ($in == ".") return $read;
# concat input
(PHP_OS == "WINNT") ? ($read = $read . ($read ? "\r\n" : "") . $in) : ($read = $read . "\n" . $in);
} while ($inp != ".");
return $read;
print("End input with . on line by itself.\n");
print("What is your first name?\n");
$first_name = multilineread();
print("What is your last name?\n");
$last_name = read();
print("\nHello, $first_name $last_name! Nice to meet you! \n");


Here's an easy way without readline() if you don't have it compiled in already:
  $fp = fopen("php://stdin","r");
  $line = rtrim(fgets($fp, 1024);

jcl atnospam jcl dot name

Even better than 'plz at dont dot spam' in only one line :) :
@c:\\php\\cli\\php.exe script.php %*

Change Language

Follow Navioo On Twitter
.NET Functions
Apache-specific Functions
Alternative PHP Cache
Advanced PHP debugger
Array Functions
Aspell functions [deprecated]
BBCode Functions
BCMath Arbitrary Precision Mathematics Functions
PHP bytecode Compiler
Bzip2 Compression Functions
Calendar Functions
CCVS API Functions [deprecated]
Class/Object Functions
Classkit Functions
ClibPDF Functions [deprecated]
COM and .Net (Windows)
Crack Functions
Character Type Functions
Cybercash Payment Functions
Credit Mutuel CyberMUT functions
Cyrus IMAP administration Functions
Date and Time Functions
DB++ Functions
Database (dbm-style) Abstraction Layer Functions
dBase Functions
DBM Functions [deprecated]
dbx Functions
Direct IO Functions
Directory Functions
DOM Functions
DOM XML Functions
enchant Functions
Error Handling and Logging Functions
Exif Functions
Expect Functions
File Alteration Monitor Functions
Forms Data Format Functions
Fileinfo Functions
filePro Functions
Filesystem Functions
Filter Functions
Firebird/InterBase Functions
Firebird/Interbase Functions (PDO_FIREBIRD)
FriBiDi Functions
FrontBase Functions
FTP Functions
Function Handling Functions
GeoIP Functions
Gettext Functions
GMP Functions
gnupg Functions
Haru PDF Functions
hash Functions
Hyperwave Functions
Hyperwave API Functions
i18n Functions
IBM Functions (PDO_IBM)
iconv Functions
ID3 Functions
IIS Administration Functions
Image Functions
Imagick Image Library
Informix Functions
Informix Functions (PDO_INFORMIX)
Ingres II Functions
IRC Gateway Functions
PHP / Java Integration
JSON Functions
LDAP Functions
libxml Functions
Lotus Notes Functions
LZF Functions
Mail Functions
Mailparse Functions
Mathematical Functions
MaxDB PHP Extension
MCAL Functions
Mcrypt Encryption Functions
MCVE (Monetra) Payment Functions
Memcache Functions
Mhash Functions
Mimetype Functions
Ming functions for Flash
Miscellaneous Functions
mnoGoSearch Functions
Microsoft SQL Server Functions
Microsoft SQL Server and Sybase Functions (PDO_DBLIB)
Mohawk Software Session Handler Functions
mSQL Functions
Multibyte String Functions
muscat Functions
MySQL Functions
MySQL Functions (PDO_MYSQL)
MySQL Improved Extension
Ncurses Terminal Screen Control Functions
Network Functions
Newt Functions
NSAPI-specific Functions
Object Aggregation/Composition Functions
Object property and method call overloading
Oracle Functions
ODBC Functions (Unified)
ODBC and DB2 Functions (PDO_ODBC)
OpenAL Audio Bindings
OpenSSL Functions
Oracle Functions [deprecated]
Oracle Functions (PDO_OCI)
Output Control Functions
Ovrimos SQL Functions
Paradox File Access
Parsekit Functions
Process Control Functions
Regular Expression Functions (Perl-Compatible)
PDF Functions
PDO Functions
Phar archive stream and classes
PHP Options&Information
POSIX Functions
Regular Expression Functions (POSIX Extended)
PostgreSQL Functions
PostgreSQL Functions (PDO_PGSQL)
Printer Functions
Program Execution Functions
PostScript document creation
Pspell Functions
qtdom Functions
Rar Functions
GNU Readline
GNU Recode Functions
RPM Header Reading Functions
runkit Functions
SAM - Simple Asynchronous Messaging
Satellite CORBA client extension [deprecated]
SCA Functions
SDO Functions
SDO XML Data Access Service Functions
SDO Relational Data Access Service Functions
SESAM Database Functions
PostgreSQL Session Save Handler
Session Handling Functions
Shared Memory Functions
SimpleXML functions
SNMP Functions
SOAP Functions
Socket Functions
Standard PHP Library (SPL) Functions
SQLite Functions
SQLite Functions (PDO_SQLITE)
Secure Shell2 Functions
Statistics Functions
Stream Functions
String Functions
Subversion Functions
Shockwave Flash Functions
Swish Functions
Sybase Functions
TCP Wrappers Functions
Tidy Functions
Tokenizer Functions
Unicode Functions
URL Functions
Variable Handling Functions
Verisign Payflow Pro Functions
vpopmail Functions
W32api Functions
WDDX Functions
win32ps Functions
win32service Functions
xattr Functions
xdiff Functions
XML Parser Functions
XML-RPC Functions
XMLReader functions
XMLWriter Functions
XSL functions
XSLT Functions
YAZ Functions
YP/NIS Functions
Zip File Functions
Zlib Compression Functions
eXTReMe Tracker