Executing Host Programs

PHP can call an external program that resides on a web server in a number of different ways. Let's look at them in the following sections.

The passthru Function

The simplest way to run a host command and display the output to screen is by using the passthru function. The command passed in as an argument is executed on the web server, and any resulting output is sent to the browser.

The following is a simple example that works on both Unix/Linux and Windows systems:

 passthru("hostname"); 

The command hostname is executed on the host system, and its output is displayed. The hostname command finds the system's hostname and displays it.

An optional second argument to passthru allows you to find the command's exit code. This is often useful if you want to find out whether a command succeededall programs should return an exit code of zero on successful completionor to perform a test on a command that could have several return values.

Command Output Only the standard output stream is displayed in the web browser window, so you must redirect the stderr stream if you want to see warnings and errors produced by the host command.

For instance, you can use passthru("cmd 2>&1") on a Unix server with the Bourne shell.

The most common nonzero return values are 1 for a nonspecific error and 127, which means that the command you attempted to run could not be found. Other error codes specific to a particular program are usually documented.

The following example makes a system call to the hostname command and takes an action, depending on its return code:

 passthru("hostname", $return); switch ($return) {   case 0:   echo "Command completed successfully";             break;   case 127: echo "Command could not be found";             break;   default:  echo "Command failed with code $return"; } 

Using Backticks

The backtick (`) character is a handy shortcut that can be used to indicate a system command for execution on the web server itself. A string contained between two backticks is executed, and the response produced by the host system is returned.

The following is equivalent to the passthru example, but it uses the backtick syntax:

 echo `hostname`; 

With backticks you are able to assign the result of a host command to a variable, as shown in the following statement:

 $hostname = `hostname`; 

In fact, the backtick characters can be used anywhere in a PHP script. They immediately interrupt program execution to call the host command, with the resulting values replaced into the script. The following example shows that the result of a host command can even be used within a condition:

 if (chop(`hostname`) == "hal9000") {   echo "Good evening, Dave"; } 

Because the result from hostname ends with a carriage returnso that the output when run in a command shell looks tidythe previous example uses chop to make sure that only non-whitespace characters are compared.

Exit Codes There is no way to obtain an exit code when using backticks. Instead, you should use the exec function, which works just like passthru but returns the command output as a string. The optional second argument can be used to grab the exit code.

Building Command Strings

Commands are passed as arguments to passthru or exec or are simply strings contained in backticks. Therefore, you can build up a command string by using variables or in stages if you want.

Variable substitution takes place within a double-quoted command string, but if the string is enclosed in single quotes, any identifier prefixed with a dollar sign is treated as a shell variable.

Perhaps the strangest looking statement in PHP is one where you execute a command stored in a string by using backticks. This looks as follows:

 `$cmd`; 

The variable $cmd could contain any system command and, if you really don't care what the output from the command is, this is valid.

Note, however, that the terminating semicolon is required. A closing backtick closes the host command but does not terminate a PHP statement.