Appendix B. Using PHP from the command line

The command line options of the PHP executable are useful if you would like to debug or test your PHP setup, but they can also be handy, if you would like to use PHP for a different purpose than web scripting.

Note, that you can always direct the output of the PHP executable to an external file with the > character, so php -q test.php > test.html will print out the output of test.php without HTTP headers to the test.html file in the same directory.

You can only use these command line options if you have the PHP executable. If you built the server module version, and you have no CGI version available on your machine, than you have no chance to use these options. For Windows users both the PHP executable and the server modules are in the binary package, the executable is named php.exe.

This list of command line options is consistent with PHP 4.0.6. You can get the actual list and some one line descriptions with the -h option. The output of php -h should be something like this:

Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]} -q Quiet-mode. Suppress HTTP Header output. -s Display colour syntax highlighted source. -f <file> Parse <file>. Implies `-q' -v Version number -C Do not chdir to the script's directory -c <path> Look for php.ini file in this directory -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 -h This help

Here we list some of the most important command line options with detailed explanations.

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 -q 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 -q
<?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 and should not print out HTTP headers. 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 -q 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.