PHP is most often used in combination with a Web server, to dynamically generate Web site pages. However, this Web server interface isn’t the only way to use PHP, because the PHP distribution also includes a command-line interface which can be used to run PHP programs at the command prompt, much like Perl or bash.
This document will introduce you to PHP’s command-line interface (CLI), showing you how to interact with PHP programs at the command prompt.
Executable
All PHP distributions, whether compiled from source or pre-built, include a PHP executable by default. This executable can be used to run command-line PHP programs.
To locate this executable on your system, use the following guidelines:
- On Windows, it will be stored in your main PHP installation folder as php.exe or (in older PHP versions) php-cli.exe.
- On Linux, it will be stored in the bin/ sub-directory of your PHP installation directory.
In either case, you can test it to ensure that it works, by calling it with the -v option:
shell> /path/to/php -v
PHP 5.0.0 (cli) (built: Jun 1 2005 18:32:10)
Copyright (c) 1997-2004 The PHP Group
Zend Engine v2.0.0, Copyright (c) 1998-2004 Zend Technologies
This should return the PHP version number.
A simple PHP CLI program
Once you’ve located the CLI executable, try it out with a simple program. Create a text file containing the following PHP code, and save it as hello.php:
<?php
echo “Hello from the CLI”;
?>
Now, try running this program at the command prompt, by invoking the CLI executable and passing it the name of the script to run:
shell> /path/to/phphello.php
Hello from the CLI
Using standard input and output
The PHP CLI defines three constants, to make it easier to interact with the interpreter at the command prompt. These are shown in Table A.
Table A
|
Constant |
Description |
| STDIN | The standard input device |
| STDOUT | The standard output device |
| STDERR | The standard error device |
You can use these constants within your PHP script to accept user input, or display the results of processing and calculation. To understand this better, consider the following script: (Listing A)
Listing A
<?php
// ask for input
fwrite(STDOUT, “Enter your name: “);
// get input
$name = trim(fgets(STDIN));
// write input back
fwrite(STDOUT, “Hello, $name!”);
?>
Look what happens when you run it:
shell> /path/to/phphello.php
Enter your name: Joe
Hello, Joe!
In this script, the fwrite() function first writes a message to the standard output device asking for the user’s name. The user’s input is then read into a PHP variable from the standard input device, and incorporated into a string. This string is then printed back to the standard output device withfwrite().
Using command-line arguments
It’s common to pass programs options on the command line to modify their behavior. You can do this with your CLI programs as well. The PHP CLI comes with two special variables designed specifically for this purpose: the $argv array, which stores the options passed to the PHP script on the command line as individual array elements, and the $argc variable, which stores the number of elements in the $argv array.
It’s simple to write code within your PHP script to read $argv and process the options it contains. Try the illustrative script in Listing B to see how it works:
Listing B
<?php
print_r($argv);
?>
Run this script by passing it some arbitrary values, and check the output:
shell> /path/to/phptest.php chocolate 276 “killer tie, dude!”
Array
(
[0] => test.php
[1] => chocolate
[2] => 276
[3] => killer tie, dude!
)
As you can see from the output, the values passed to test.php automatically appear in $argv as array elements. Notice that the first argument to $argvis always the name of the script itself.
Here’s another, more advanced example: (Listing C)
Listing C
<?php
// check for all required arguments
// first argument is always name of script!
if ($argc != 4) {
die(“Usage: book.php <check-in-date> <num-nights> <room-type>\n”);
}
// remove first argument
array_shift($argv);
// get and use remaining arguments
$checkin = $argv[0];
$nights = $argv[1];
$type = $argv[2];
echo “You have requested a $type room for $nights nights, checking in on $checkin. Thank you for your order!\n”;
?>
Here’s an example of its usage:
shell> /path/to/phpbook.php 21/05/2005 7 single
You have requested a single room for 7 nights, checking in on 21/05/2005. Thank you for your order!
Here, the script first checks the $argc to ensure that the required number of arguments are present. It then extracts each argument from $argv and prints them back out to the standard output device.
Note: You can add more sophisticated command-line option parsing to PHP with theConsole_Getopt PEAR class.
Using CLI options
In addition to passing your PHP script options on the command line, you can also pass the PHP CLI options to alter its behavior. Table B contains a list of the important ones:
Table B
|
Option |
Description |
| -a | Run interactively |
| -c path | Read php.ini file from path |
| -n | Run without reading php.ini |
| -m | List compiled modules |
| -i | Display information about the PHP build |
| -l | Syntax-check a PHP script |
| -s | Display color-coded source |
| -w | Display source code after stripping comments |
| -h | Display help |
Interactive use
You can also use the PHP CLI interactively, typing in commands and receiving an immediate response. To see this in action, invoke the CLI executable without any options, as below:
shell> /path/to/php -a
You will be presented with a blank line, at which you can type in PHP code. Take a look:
shell> /path/to/php -a
Interactive mode enabled
<?php
echo mktime();
1121187283
echo 2+2;
4
exit();
shell>
Alternatively, you can invoke the CLI without the -a parameter, and type in a complete script or code block. Use <Ctrl>-D to end the code block and have the CLI execute it. Here’s an example:
shell> /path/to/php
<?php
echo date(“d-M-Y h:i:s”, time());
?>
<Ctrl-D>
12-Jul-2005 06:54:04
And that’s about it! You should now know enough about the PHP CLI to begin using it yourself. Have fun, and happy coding!