Working with PHP CLI

Developing applications designed to run from a terminal instead of through a Web browser requires us, as developers, to look a bit differently at the way scripts are written. For instance, when developing shell scripts in PHP, you do not need to be concerned with things such as sessions (the "stateless" protocol problem does not apply to client-side scripts). However, new problems arise when you attempt to design scripts that require interaction with the user because we no longer can rely on the $_GET, $_POST, and $_COOKIE superglobals for input or HTML for output. Instead of these facilities, to interact with the user, your scripts must instead rely on CLI-specific extensions and third-party applications.

Command-Line Arguments and Return Codes

One of the first new ways of accepting input from the user in CLI scripts is to use command-line arguments. These arguments are passed to your scripts when they are executed and generally enable or define certain options. An example of a command-line argument is the -h argument passed to the PHP executable (which displayed a list of all available argumentssee the previous section). To receive a list of command-line arguments in PHP, you'll need to be familiar with two predefined variables: $argc and $argv. These two variables (abbreviations for argument count and argument values) store all the information passed to your scripts in the form of command-line arguments. As you may have already guessed, the $argc parameter is an integer count of the total number of arguments passed, and $argv is an integer array of the value(s) of those arguments in the order they were passed. Every CLI PHP script that is executed will always have at least one argument provided to it. This argument represents the filename of the script currently being executed.

NOTE

Although $argc is the number of arguments passed to the PHP script, it will always be one greater than expected. This is because regardless of what parameters are passed to the PHP script, the first parameter $argv[0] is always the name of the script being executed. This allows the developer to refer to the executing application without risking it being wrong (for instance if the user decided to rename the application filename).

For an example of using command-line arguments in CLI PHP scripts, see Listing 17.1:

Listing 17.1. Using $argc and $argv in CLI PHP

 <?php     if(!isset($argv[1]) || ($argv[1] != "-d")) {         echo "Usage:\n";         echo "\n{$argv[0]} -d\n";         exit(-1);     }     echo "You passed the command line argument '-d'\n";     exit(0); ?> 

NOTE

Another oddity with the CLI version of PHP is that line breaks are no longer determined by the HTML <BR> tag. To place text on the next line, you'll have to use a newline character, as shown.

As you can see, this script is designed to accept a single command-line argument -d. If anything other than this parameter is passed, the script will halt execution. It is here that we realize yet another difference when developing CLI scriptsreturn codes.

When you develop client-side scripts, especially if they are scripts designed to be used in conjunction with other programs, using return codes is highly recommended. When you use return codes (also known as exit codes) in CLI scripts via the exit statement, they behave almost identically to using the return statement for functions. Instead of returning a value back into the PHP script, however, the exit code is given to the operating system and can be used to indicate whether your script was "successful" (or to indicate the error that occurred) in the task it was accomplishing. As you can see, the example in Listing 17.1 has two different exit codes: -1 (indicating an error) and 0 (indicating success). Although you may decide on using a different exit code in the event of an error, it is accepted practice that an exit code of 0 indicates a successful execution. Other than this rule, exit codes can be any value between 0 and 255.

NOTE

Attempting to use an exit code larger than 255 will result in the exit code value returned to "wrap around" back to 0 (the exit code modulus 256). Therefore, an exit code in PHP of 256 will return as 0 to the operating system.