Using PHP from the command line

Introduction

The main focus of Sapi is for developing shell applications with PHP. There are quite a few differences between the Sapi and other SAPIs which are explained in this chapter. It is worth mentioning that Cli and CGI are different SAPIs although they do share many of the same behaviors.

The Sapi is enabled by default using --enable-cli, but may be disabled using the --disable-cli option when running ./configure.

The name, location and existence of the Cli/CGI binaries will differ depending on how PHP is installed on your system. By default when executing make, both the CGI and Cli are built and placed as sapi/cgi/php-cgi and sapi/cli/php respectively, in your PHP source directory. You will note that both are named php. What happens during make install depends on your configure line. If a module SAPI is chosen during configure, such as apxs, or the --disable-cgi option is used, the Cli is copied to {PREFIX}/bin/php during make install otherwise the CGI is placed there. So, for example, if --with-apxs is in your configure line then the Cli is copied to {PREFIX}/bin/php during make install. If you want to override the installation of the CGI binary, use make install-cli after make install. Alternatively you can specify --disable-cgi in your configure line.

The Cli binary is distributed in the main folder as php.exe on Windows. The CGI version is distributed as php-cgi.exe. Additionally, a php-win.exe is distributed if PHP is configured using --enable-cli-win32. This does the same as the Cli version, except that it doesn't output anything and thus provides no console.

Differences to other SAPIs

Remarkable differences of the Cli SAPI compared to other SAPIs:

• Unlike the CGI SAPI, no headers are written to the output.

  Though the CGI SAPI provides a way to suppress HTTP headers, there's no equivalent switch to enable them in the Sapi.

  Cli is started up in quiet mode by default, though the -q and --no-header switches are kept for compatibility so that it is possible to use older CGI scripts.

  It does not change the working directory to that of the script. (-C and --no-chdir switches kept for compatibility)

  Plain text error messages (no HTML formatting).

• There are certain Ini directives which are overridden by the Sapi because they do not make sense in shell environments:

  Directive	Cli SAPI default value	Comment
  html_errors	false	Defaults to false, as it can be quite hard to read error messages in the shell environment when they are cluttered up with uninterpreted HTML tags.
  implicit_flush	true	In a shell environment, it is usually desirable for output, such as from print(), echo() and friends, to be displayed immediately, and not held in a buffer. Nonetheless, it is still possible to use output buffering to defer or manipulate standard output.
  max_execution_time	0 (unlimited)	PHP in a shell environment tends to be used for a much more diverse range of purposes than typical Web-based scripts, and as these can be very long-running, the maximum execution time is set to unlimited.
  register_argc_argv	true	Setting this to true means that scripts executed via the Cli SAPI always have access to argc (number of arguments passed to the application) and argv (array of the actual arguments).The PHP variables $argc and $argv are automatically set to the appropriate values when using the Cli SAPI. These values can also be found in the $_SERVER array, for example: $_SERVER['argv'].The presence of $argv or $_SERVER['argv'] is not a reliable indication that a script is being run from the command line because they may be set in other contexts when register_argc_argv is enabled. The value returned by php_sapi_name() should be checked instead. <?php if (php_sapi_name() === 'cli') { echo "This is being run from the command line!\n"; } Feature-8-5-0
  output_buffering	false	Although the Ini setting is hardcoded to false, the Output buffering functions are available.
  max_input_time	false	The PHP Cli does not support GET, POST or file uploads.

  Note

  These directives cannot be initialized with another value from the configuration file Ini or a custom one (if specified). This limitation is because the values are applied after all configuration files have been parsed. However, their values can be changed during runtime (although this is not sensible for all of them, such as register_argc_argv).

  Note

  It is recommended to set ignore_user_abort for command line scripts. See ignore_user_abort() for more information.

• To ease working in the shell environment, a number of constants are defined for I/O streams.

• The Sapi does not change the current directory to the directory of the executed script.

  Example showing the difference to the CGI SAPI:

  phpCopy

  <?php
  // Our simple test application named test.php
  echo getcwd(), "\n";
  ?>

  When using the CGI version, the output is:

  output

  $ pwd
  /tmp
  
  $ php -q another_directory/test.php
  /tmp/another_directory

  This clearly shows that PHP changes its current directory to the one of the executed script.

  Using the Sapi yields:

  output

  $ pwd
  /tmp
  
  $ php -f another_directory/test.php
  /tmp

  This allows greater flexibility when writing shell tools in PHP.

  Note

  The CGI SAPI supports this Sapi behaviour by means of the -C switch when run from the command line.

Command line options

The list of command line options provided by the PHP binary can be queried at any time by running PHP with the -h switch:

Usage: php [options] [-f] <file> [--] [args...]
   php [options] -r <code> [--] [args...]
   php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
   php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
   php [options] -- [args...]
   php [options] -a

  -a               Run interactively
  -c <path>|<file> Look for php.ini file in this directory
  -n               No php.ini file will be used
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -f <file>        Parse and execute <file>.
  -h               This help
  -i               PHP information
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -r <code>        Run PHP <code> without using script tags <?..?>
  -B <begin_code>  Run PHP <begin_code> before processing input lines
  -R <code>        Run PHP <code> for every input line
  -F <file>        Parse and execute <file> for every input line
  -E <end_code>    Run PHP <end_code> after processing all input lines
  -H               Hide any passed arguments from external tools.
  -S <addr>:<port> Run with built-in web server.
  -t <docroot>     Specify document root <docroot> for built-in web server.
  -s               Output HTML syntax highlighted source.
  -v               Version number
  -w               Output source with stripped comments and whitespace.

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

  --ini            Show configuration file names

  --rf <name>      Show information about function <name>.
  --rc <name>      Show information about class <name>.
  --re <name>      Show information about extension <name>.
  --rz <name>      Show information about Zend extension <name>.
  --ri <name>      Show configuration for extension <name>.

Executing PHP files

There are three different ways of supplying the Sapi with PHP code to be executed:

1. Tell PHP to execute a certain file.

   output

   $ php my_script.php
   
   $ php -f my_script.php

   Both ways (whether using the -f switch or not) execute the file my_script.php. Note that there is no restriction on which files can be executed; in particular, the filename is not required have a .php extension.

2. Pass the PHP code to execute directly on the command line.

   output

   $ php -r 'print_r(get_defined_constants());'

   Special care has to be taken with regard to shell variable substitution and usage of quotes.

   Note

   Read the example carefully: there are no beginning or ending tags! The -r switch simply does not need them, and using them will lead to a parse error.

3. Provide the PHP code to execute via standard input (stdin).

   This gives the powerful ability to create PHP code dynamically and feed it to the binary, as shown in this (fictional) example:

   output

   $ some_application | some_filter | php | sort -u > final_output.txt

You cannot combine any of the three ways to execute code.

As with every shell application, the PHP binary accepts a number of arguments; however, the PHP script can also receive further arguments. The number of arguments that can be passed to your script is not limited by PHP (and although the shell has a limit to the number of characters which can be passed, this is not in general likely to be hit). The arguments passed to the script are available in the global array $argv. The first index (zero) always contains the name of the script as called from the command line. Note that, if the code is executed in-line using the command line switch -r, the value of $argv[0] will be "Standard input code"; prior to PHP 7.2.0, it was a dash ("-") instead. The same is true if the code is executed via a pipe from STDIN.

A second global variable, $argc, contains the number of elements in the $argv array (not the number of arguments passed to the script).

As long as the arguments to be passed to the script do not start with the - character, there's nothing special to watch out for. Passing an argument to the script which starts with a - will cause trouble because the PHP interpreter thinks it has to handle it itself, even before executing the script. To prevent this, use the argument list separator --. After this separator has been parsed by PHP, every following argument is passed untouched to the script.

# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# This will pass the '-h' argument to the script and prevent PHP from showing its usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

However, on Unix systems there's another way of using PHP for shell scripting: make the first line of the script start with #!/usr/bin/php (or whatever the path to your PHP Cli binary is if different). The rest of the file should contain normal PHP code within the usual PHP starting and end tags. Once the execution attributes of the file are set appropriately (e.g. chmod +x test), the script can be executed like any other shell or perl script:

Execute PHP script as shell script

#!/usr/bin/php
<?php
var_dump($argv);
?>

Assuming this file is named test in the current directory, it is now possible to do the following:

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

As can be seen, in this case no special care needs to be taken when passing parameters starting with -.

The PHP executable can be used to run PHP scripts absolutely independent of the web server. On Unix systems, the special #! (or "shebang") first line should be added to PHP scripts so that the system can automatically tell which program should run the script. On Windows platforms, it's possible to associate php.exe with the double click option of the .php extension, or a batch file can be created to run scripts through PHP. The special shebang first line for Unix does no harm on Windows (as it's formatted as a PHP comment), so cross platform programs can be written by including it. A simple example of writing a command line PHP program is shown below.

Script intended to be run from command line (script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

This is a command line PHP script with one option.

  Usage:
  <?php echo $argv[0]; ?> <option>

  <option> can be some word you would like
  to print out. With the --help, -help, -h,
  or -? options, you can get this help.

<?php
} else {
    echo $argv[1];
}
?>

The script above includes the Unix shebang first line to indicate that this file should be run by PHP. We are working with a Cli version here, so no HTTP headers will be output.

The program first checks that there is the required one argument (in addition to the script name, which is also counted). If not, or if the argument was --help, -help, -h or -?, the help message is printed out, using $argv[0] to dynamically print the script name as typed on the command line. Otherwise, the argument is echoed out exactly as received.

To run the above script on Unix, it must be made executable, and called simply as script.php echothis or script.php -h. On Windows, a batch file similar to the following can be created for this task:

Batch file to run a command line PHP script (script.bat)

@echo OFF
"C:\php\php.exe" script.php %*

Assuming the above program is named script.php, and the Cli php.exe is in C:\php\php.exe, this batch file will run it, passing on all appended options: script.bat echothis or script.bat -h.

See also the Readline extension documentation for more functions which can be used to enhance command line applications in PHP.

On Windows, PHP can be configured to run without the need to supply the C:\php\php.exe or the .php extension, as described in Command Line PHP on Microsoft Windows.

Input/output streams

The Sapi defines a few constants for I/O streams to make programming for the command line a bit easier.

Given the above, you don't need to open e.g. a stream for stderr yourself but simply use the constant instead of the stream resource:

php -r 'fwrite(STDERR, "stderr\n");'

You do not need to explicitly close these streams, as they are closed automatically by PHP when your script ends.

Interactive shell

The Sapi provides an interactive shell using the -a option if PHP is compiled with the --with-readline option. As of PHP 7.1.0 the interactive shell is also available on Windows, if the readline extension is enabled.

Using the interactive shell you are able to type PHP code and have it executed directly.

Executing code using the interactive shell

$ php -a
Interactive shell

php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php >

The interactive shell also features tab completion for functions, constants, class names, variables, static method calls and class constants.

Tab completion

Pressing the tab key twice when there are multiple possible completions will result in a list of these completions:

php > strp[TAB][TAB]
strpbrk   strpos    strptime  
php > strp

When there is only one possible completion, pressing tab once will complete the rest on the same line:

php > strpt[TAB]ime(

Completion will also work for names that have been defined during the current interactive shell session:

php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName

The interactive shell stores your history which can be accessed using the up and down keys. The history is saved in the ~/.php_history file. As of PHP 8.4.0, the path to the history file can be set using the PHP_HISTFILE environment variable.

The Sapi provides the Ini settings cli.pager and cli.prompt. The cli.pager setting allows an external program (such as less) to act as a pager for the output instead of being displayed directly on the screen. The cli.prompt setting makes it possible to change the php > prompt.

It is also possible to set Ini settings in the interactive shell using a shorthand notation.

Setting Ini settings in the interactive shell

The cli.prompt setting:

php > #cli.prompt=hello world :> 
hello world :> 

Using backticks it is possible to have PHP code executed in the prompt:

php > #cli.prompt=`echo date('H:i:s');` php > 
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php > 

Setting the pager to less:

php > #cli.pager=less
php > phpinfo();
(output displayed in less)
php > 

The cli.prompt setting supports a few escape sequences:

Interactive mode

If the readline extension is not available, prior to PHP 8.1.0, invoking the Sapi with the -a option provided the interactive mode. In this mode, a complete PHP script is supposed to be given via STDIN, and after termination with CTRLD (POSIX) or CTRLZ followed by ENTER (Windows), this script is evaluated. This is basically the same as invoking the Sapi without the -a option.

As of PHP 8.1.0, invoking the Sapi with the -a option fails, if the readline extension is not available.

Built-in web server

The Sapi provides a built-in web server.

The web server runs only one single-threaded process, so PHP applications will stall if a request is blocked.

URI requests are served from the current working directory where PHP was started, unless the -t option is used to specify an explicit document root. If a URI request does not specify a file, then either index.php or index.html in the given directory are returned. If neither file exists, the lookup for index.php and index.html will be continued in the parent directory and so on until one is found or the document root has been reached. If an index.php or index.html is found, it is returned and $_SERVER['PATH_INFO'] is set to the trailing part of the URI. Otherwise a 404 response code is returned.

If a PHP file is given on the command line when the web server is started it is treated as a "router" script. The script is run at the start of each HTTP request. If this script returns false, then the requested resource is returned as-is. Otherwise the script's output is returned to the browser.

Standard MIME types are returned for files with extensions:

• .3gp
• .apk
• .avi
• .bmp
• .css
• .csv
• .doc
• .docx
• .flac
• .gif
• .gz
• .gzip
• .htm
• .html
• .ics
• .jpe
• .jpeg
• .jpg
• .js
• .kml
• .kmz
• .m4a
• .mov
• .mp3
• .mp4
• .mpeg
• .mpg
• .odp
• .ods
• .odt
• .oga
• .ogg
• .ogv
• .pdf
• .png
• .pps
• .pptx
• .qt
• .svg
• .swf
• .tar
• .text
• .tif
• .txt
• .wav
• .webm
• .wmv
• .xls
• .xlsx
• .xml
• .xsl
• .xsd
• .zip

.

As of PHP 7.4.0, the built-in webserver can be configured to fork multiple workers in order to test code that requires multiple concurrent requests to the built-in webserver. Set the PHP_CLI_SERVER_WORKERS environment variable to the number of desired workers before starting the server.

Starting the web server

$ cd ~/public_html
$ php -S localhost:8000

The terminal will show:

PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit

After URI requests for http://localhost:8000/ and http://localhost:8000/myscript.html the terminal will show something similar to:

PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit.
[Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
[Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
[Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
[Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
[Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Note that prior to PHP 7.4.0, symlinked statical resources have not been accessible on Windows, unless the router script would handle these.

Starting with a specific document root directory

$ cd ~/public_html
$ php -S localhost:8000 -t foo/

The terminal will show:

PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
Listening on localhost:8000
Document root is /home/me/public_html/foo
Press Ctrl-C to quit

Using a Router Script

In this example, requests for images will display them, but requests for HTML files will display "Welcome to PHP":

<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
    return false;    // serve the requested resource as-is.
} else { 
    echo "<p>Welcome to PHP</p>";
}
?>

$ php -S localhost:8000 router.php

Checking for CLI Web Server Use

To reuse a framework router script during development with the CLI web server and later also with a production web server:

<?php
// router.php
if (php_sapi_name() == 'cli-server') {
    /* route static assets and return false */
}
/* go on with normal index.php operations */
?>

$ php -S localhost:8000 router.php

Handling Unsupported File Types

If you need to serve a static resource whose MIME type is not handled by the CLI web server, use:

<?php
// router.php
$path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
if ($path["extension"] == "el") {
    header("Content-Type: text/x-script.elisp");
    readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
    return FALSE;
}
?>

$ php -S localhost:8000 router.php

Accessing the CLI Web Server From Remote Machines

You can make the web server accessible on port 8000 to any interface with:

$ php -S 0.0.0.0:8000

INI settings

Title

cli_server.colorbool

Enable the built-in development web server to use ANSI color coding in terminal output.