�� 25. Using PHP from the command line

Since version 4.3, PHP supports a new SAPI type (Server Application Programming Interface) named CLI which means Command Line Interface. As the name implies, this SAPI type main focus is on developing shell (or desktop as well) applications with PHP. There are quite some differences between the CLI SAPI and other SAPIs which are further explained throughout this chapter.

The CLI SAPI was released for the first time with PHP 4.2.0, but was still experimental back then and had to be explicitely enabled with --enable-cli when running ./configure. Since PHP 4.3.0 the CLI SAPI is no longer experimental and is therefore always built and installed as the php (called php.exe on Windows) binary.

Remarkable differences of the CLI SAPI compared to other SAPIs:

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

  Though the CGI SAPI provies a way to suppress HTTP headers, there's not equivalent switch to enable them in the CLI SAPI.

• The are certain php.ini directives which are overriden by the CLI SAPI because the do not make sense in shell environments:

  ��� 25-1. Overriden php.ini directives

  Directive	CLI SAPI default value	Comment
  html_errors	FALSE	It can be quite hard to read the error message in your shell when it's cluttered with all those meaningless HTML tags, therefore this directive defaults to FALSE.
  implicit_flush	TRUE	It is desired that any output coming from print(), echo() and friends is immidiately written to the output and not cached in any buffer. You still can use output buffering if you want to defer or manipulate standard output.
  max_execution_time	0 (unlimited)	Due to endless possibilities of using PHP in shell environments, the maximum execution time has been set to unlimited. Whereas applications written for the web are executed within splits of a seconds, shell application tend to have a much longer execution time.
  register_argc_argv	TRUE	The global PHP variables $argc (number of arguments passed to the application) and $argv (array of the actual arguments) are always registered and filled in with the appropriate values when using the CLI SAPI.

  ע: These directives cannot be initialzied with another value from the configuration file php.ini or a custom one (if specified). This is a limitation because those default values are applied after all configuration files have been parsed. However, their value can be changed during runtime (which does not make sense for all of those directives, e.g. register_argc_argv).

• To ease working in the shell environment, the following constants are defined:

  ��� 25-2. CLI specific Constants

  Constant	Description
  STDIN	An already opened stream to stdin. This saves opening it with $stdin = fopen('php://stdin', 'r');
  STDOUT	An already opened stream to stdout. This saves opening it with $stdout = fopen('php://stdout', 'w');
  STDERR	An already opened stream to stdout. This saves opening it with $stderr = fopen('php://stderr', 'w');

  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, this is automatically done by PHP.

• The CLI SAPI does not change the current directory to the directory of the executed script !

  Example showing the difference to the CGI SAPI:

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

  When using the CGI version, the output is

  $ pwd /tmp $ php-cgi -f 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 CLI SAPI yields:

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

  This allows greater flexibility when writing shell tools in PHP.

  ע: The CGI SAPI supports the CLI SAPI behaviour by means of the -C switch when ran from the command line.

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

Usage: php [options] [-f] <file> [args...] php [options] -r <code> [args...] php [options] [-- args...] -s Display colour syntax highlighted source. -w Display source with stripped comments and whitespace. -f <file> Parse <file>. -v Version number -c <path>|<file> Look for php.ini file in this directory -a Run interactively -d foo[=bar] Define INI entry foo with value 'bar' -e Generate extended information for debugger/profiler -z <file> Load Zend extension <file>. -l Syntax check only (lint) -m Show compiled in modules -i PHP information -r <code> Run PHP <code> without using script tags <?..?> -h This help args... Arguments passed to script. Use -- args when first argument starts with - or script is read from stdin

The CLI SAPI has three different ways of getting the PHP code you want to execute:

1. Telling PHP to execute a certain file.

   php my_script.php php -f my_script.php

   Both ways (using the -f switch or not) execute the given file my_script.php. You can choose any file to execute, your PHP scripts do not have to end with the .php extension but can give them any name or extension you want them to have.

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

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

   Special care has to be taken in regards of shell variable substitution and quoting usage.

   ע: Read the example carefully, thera are no beginning or ending tags! The -r switch simply does not need them. Using them will lead to a parser error.

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

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

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

Like every shell application, the PHP binary accepts a number of arguments but also your PHP script can receive them. The number of arguments which can be passed to your script is not limited by PHP (the shell has a certain size limit in numbers of characters which can be passed; usually you won't hit this limit). The arguments passed to your script are available in the global array $argv. The zero index always contains the script name (which is - in case the PHP code is coming from either standard input or from the command line switch -r). The second registered global variable is $argc which contains the number of elements in the $argv array (not the number of arguments passed to the script).

As long as the arguments you want to pass to your script do not start with the - character, there's nothing special to watch out for. Passing an argument to your script which starts with a - will cause trouble because PHP itself thinks it has to handle it. To prevent this use the argument list separator --. After the argument has been parsed by PHP, every argument following it is passed untoched/unparsed to your 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 your script and prevent PHP from showing it's usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

However, there's another way of using PHP for shell scripting. You can write a script where the first line starts with #!/usr/bin/php and then following the normal PHP code included within the PHP starting and end tags and set the execution attributes of the file appropriately. This way it can be executed like a normal shell or perl script:

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

Assuming this file is named test in the current directory, we can now do the following:

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

As you see no care has to be taken when passing parameters to your script which start with -.

The PHP executable can be used to run PHP scripts absolutely independent from the web server. If you are on a Unix system, you should add a special first line to your PHP script, and make it executable, so the system will know, what program should run the script. On a Windows platform you can associate php.exe with the double click option of the .php files, or you can make a batch file to run the script through PHP. The first line added to the script to work on Unix won't hurt on Windows, so you can write cross platform programs this way. A simple example of writing a command line PHP program can be found below.

#!/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];
}
?>

In the script above, we used the special first line to indicate, that this file should be run by PHP. We work with a CLI version here, so there will be no HTTP header printouts. There are two variables you can use while writing command line applications with PHP: $argc and $argv. The first is the number of arguments plus one (the name of the script running). The second is an array containing the arguments, starting with the script name as number zero ($argv[0]).

In the program above we checked if there are less or more than one arguments. Also if the argument was --help, -help, -h or -?, we printed out the help message, printing the script name dynamically. If we received some other argument we echoed that out.

If you would like to run the above script on Unix, you need to make it executable, and simply call it as script.php echothis or script.php -h. On Windows, you can make a batch file for this task:

@c:\php\php.exe script.php %1 %2 %3 %4

Assuming, you named the above program as script.php, and you have your php.exe in c:\php\php.exe this batch file will run it for you with your added options: script.bat echothis or script.bat -h.

See also the Readline extension documentation for more functions you can use to enhance your command line applications in PHP.