PHP is a sufficiently rich programming environment that it is not common that I truly need to execute external programs on the server on which it executes. However, every once in a while, this situation does come along, and for these, it is important to understand the options that PHP provides, what their differences are, and their relative strengths and weaknesses.

There are four primary choices for executing external programs in PHP:

• The system function.
• The exec function.
• The shell_exec function or its syntactic analogue, the backtick operator, ( ` ).
• the passthru function.

We will first discuss the usage of these three functions in their most basic forms.

The system() Function

The system function in PHP takes a string argument with the command to execute as well as any arguments you wish passed to that command. This function executes the specified command, and dumps any resulting text to the output stream (either the HTTP output in a web server situation, or the console if you are running PHP as a command line tool). The return of this function is the last line of output from the program, if it emits text output.

For example:

// Windows Users replace "ls ..." with "dir ..."
$lastLine = system('ls /Users/marcwan');
echo "<br/>LastLine: $lastLine<br/>\\n";

The output of this command on my system is:

Desktop Documents Download Library Movies Music Pictures
  Public Sites bin blah.php books make1.png make1.tiff media src
  yici1.png yici1.tiff
LastLine: yici1.tiff

The return value of the function will be FALSE if the function completely fails to execute.

In addition to the return value of the system function, however, there is also the question of the return status of the program being executed (just as functions in PHP all have return values (NULL if you don’t explicitly choose one), all commands executed in most operating systems also have return values, typically a 32bit integer value). For those programs you are executing whose return status you wish to know, you can pass a second argument to the system function, which tells PHP where to put this value.

For example:

// define this variable here so that it can actually be used in the system fn
$returnValue = -1;
system('ls /Users/marcwan', $returnValue);
echo "Return Value: $returnValue<br/>\\n";

The output of this program will be:

Desktop Documents Download Library Movies Music Pictures
  Public Sites bin blah.php books make1.png make1.tiff media src
  yici1.png yici1.tiff
Return Value: 0

For most modern operating systems, a return value of 0 is considered a success, and other values indicate failure. Some programs will have a range of values to indicate the exact way in which they failed while others will just return 1 or -1 to indicate that they were unsuccessful.

The exec() Function

The system function is quite useful and powerful, but one of the biggest problems with it is that all resulting text from the program goes directly to the output stream. There will be situations where you might like to format the resulting text and display it in some different way, or not display it at all.

For this, the exec function in PHP is perfectly adapted. Instead of automatically dumping all text generated by the program being executed to the output stream, it gives you the opportunity to put this text in an array returned in the second parameter to the function:

// you define this variable here so that it exists for the call to exec
$output = null;

// Windows users: 'dir c:\\' or something similar
exec('ls /Users/marcwan', $output);
echo "<pre>" . var_export($output, TRUE) . "</pre>\\n";

Once again, on my machine, the following output is printed:

array (
  0 => 'Desktop',
  1 => 'Documents',
  2 => 'Download',
  3 => 'Library',
  4 => 'Movies',
  5 => 'Music',
  6 => 'Pictures',
  7 => 'Public',
  8 => 'Sites',
  9 => 'bin',
  10 => 'blah.php',
  11 => 'books',
  12 => 'make1.png',
  13 => 'make1.tiff',
  14 => 'media',
  15 => 'src',
  16 => 'yici1.png',
  17 => 'yici1.tiff',
)

Of course, instead of just directly emitting this output, we could instead choose to process it and only emit those files with a ’.png’ extension, for example:

foreach ($output as $fileName)
{
  if (strtolower(substr($fileName, -4)) == '.png')
    echo "<br/>$fileName\\n";
}

And once again, you can get the return code from the exec function as follows:

$output = null;
$returnValue = -1;
exec('ls /Users/marcwan', $output, $returnValue);
echo "Return Value: $returnValue<br/>\\n";
echo "<pre>" . var_export($output, TRUE) . "</pre>\\n";

The shell_exec() Function

Most of the programs we have been executing thus far have been, more or less, real programs¹. However, the environment in which Windows and Unix users operate is actually much richer than this. Windows users have the option of using the Windows Command Prompt program, cmd.exe (See Figure 1). This program is known as a command shell.

Figure 1— The Windows Command Prompt

Similarly, Unix (and Mac OS X) users can run a command shell such as sh, bash, or csh (see Figure 2). These are typically quite advanced interactive systems that allow elabourate scripts such as for x in *.png; do echo $x; done to be executed.

Figure 2— bash on Mac OS X

On both Windows and Unix, the commands for the various command shells can be put into files and executed by these programs. On Windows, convention has it that these script file have the extension .cmd while on Unix it is not uncommon to see .sh.

For those sitautions where we want to run these shell scripts from within PHP, we can use the shell_exec function, as follows:

// lists all .bat files anywhere in the system
$output = shell_exec('FOR /R C:\\ IN (*.bat) DO echo %x');   // Windows

// lists all .png files in /Users/marcan only
$output = shell_exec('for x in /Users/marcwan/*.png; do echo $x; done'); // Unix

echo "<pre>" . var_export($output, TRUE) . "</pre>\\n";

On my system this produces:

'/Users/marcwan/make1.png
/Users/marcwan/yici1.png
'

PHP also has a syntactic operator called the backtick operator which does the exact same thing as the shell_exec function. Instead of calling the shell_exec function, you simply wrap the command in the backtick character, `, which is very different from the single quote character '.

// lists all .bat files anywhere in the system
$output = `FOR /R C:\\ IN (*.bat) DO echo %x`; // Windows

// lists all .png files in /Users/marcan only
$output = `for x in /Users/marcwan/*.png; do echo $x; done`; // Unix

echo "<pre>" . var_export($output, TRUE) . "</pre>\\n";

It is worth noting that I avoid this operator at all times as it is not easy to spot in code, and I like potential security trouble spots to be as visible as humanly possible.

The passthru() Function

One fascinating function that PHP provides similar to those we have seen so far is the passthru function. This function, like the others, executes the program you tell it to. However, it then proceeds to immediately send the raw output from this program to the output stream with which PHP is currently working (i.e. either HTTP in a web server scenario, or the shell in a command line version of PHP).

When would this be useful? When you are working with image files and want to execute a program to show or otherwise manipulate these files. A most simple example would be as follows:

/**
 * Windows:
 */
header('Content-Type: image/bmp');
passthru('type c:\\Windows\\zapotec.bmp');

/**
 * Unix
 */
header('Content-Type: image/jpg');
passthru('cat /Users/marcwan/yici1.png');

The result will be an image in your browser. This is extremely powerful if you want to use some programs to resize or otherwise manipulate image files and then just dump the output to the client. There are a number of interesting utilities that come with various JPEG source code distributions that do exactly this and are powerful tools.

Are We Done Yet?

Armed with this basic knowledge, we have a one major thing left to deal with before we go off into the real world and begin using these functions: Security.

For example, the following code is simply a recipe for disaster:

$output = shell_exec('cat /webserver/info/user_files/' . $_POST['user_info_file']);
echo $output

If a malicious user were to set the value of the user_info_file post variable to bob; cat /etc/passwd. The output of both files would now be dumped, which is definitely not in your best interests.

There are two key ways which we will get around this:

1. We will design our web applications carefully for security. If we can design the web application in such a way that only we choose the file names and programs that execution functions work with, we have much less to worry about in terms of security. We can also do our best to isolate any files that we work with and try to limit damage whenever something unexpected occurs.
2. For those cases where we decide that user input is absolutely unavoidable, we will filter the user input extremely heavily and make sure it is as safe as possible before passing it to any of these functions. I always do the following:
   • Absolutely forbid the use of any slash characters, whether it be forward ( / ) or backward ( \ ). I also forbid any user strings from beginning with X:, where X could be a valid drive letter on the system (Windows only, of course).
   • Use the escapeshellarg function to further make the parameters safer. I.e. $output = shell_exec("cat /web/users/info/" . escapeshellarg($processedUserInfoFile));

A way in which we are helped by the operating system is that most web servers operate as a user with restricted permission, and thus can only do things that user is permitted to do.

One last security note we should mention here is that if your php.ini file has safe_mode set to On, then the shell_exec function and analagous backtick operator is not available.

Conclusion

We have covered a lot of ground in this article, but we should now have a solid understanding of the various execution functions available to us in PHP, as well as how they differ. While we should be extremely concerned about the security of running programs external to our web server, we can do so in a reasonably safe and controlled manner, which can only be a good thing for our web applications and their customers.

—

¹ It is worth noting that dir, type, and many other commands on Windows are not programs, but actualy commands built into the cmd.exe program. Fortunately the system execution functions are smart enough to know to execute cmd.exe for you if you ask to execute one of them.