Tip : running external programs / commands from php script

If you ever wanted to run an external command / program from inside your PHP script, PHP provides following ways to do it :

1) backticks operator

You can use `` operators. Note that these are not same as apostrophes (single quotes) ''. Generally backtick is located on the key as ~ (tilde). Whenever you use backticks operator, PHP will try to run the content contained within backticks as a shell command from current directory and the command output will be returned which can be collected by using an assignment operator. For example, after running following code :

 $file_list  = `ls -l`;

$file_list variable will contain the complete command output.

2) exec function

exec function can also be used for running external commands. We pass the shell command as first parameter. We also need to pass two more variable references as parameters, exec function fills them up with command output and command return status value respectively. Variable containing program output is an array which contains each line of command output as separate array element. The exec function itself returns the last line of command output. For example, when we run this code :

 $last_line =  exec('ls -l', $file_list, $return_code);

$last_line variable will contain last line of command output. $file_list variable will be an array containing each line of command output as a separate element. $return_code variable will contain command return status value.

3) shell_exec function

shell_exec is similar to backticks operator, we need to pass it the external command as a parameter and it will return the complete command output. For example, after this code

PHP Code:

 $output = shell_exec('ls -l'); 


$output variable will contain the complete command output.

4) system function

System function also takes the shell command to be run as its first parameter. Second parameter is a variable which passed as a reference to be filled up with command's return status value. Its different from shell_exec in the way it handles the command output. Instead of returning the complete command outoput, it only returns the last line of output. Another thing to note is that it autmatically sends the complete command output to the browser as well. For example, after running this code

$last_line = system('ls -l', $return_value);

$last_line variable will contain last line of command output. $return_value variable will contain command return status value. Complete command output will also be send to the browser by system command.

5) passthru function

passthru function is quite similar system function. It takes two parameters, first is the shell command to execute and second is a variable passed as reference used for collecting command return status value. passthru function doesn't returns any value. It sends the complete command output to the browser. This function is preferred over exec and system functions when running command which produce binary data output.


In my next post i will show you some other advanced methods as well. I will also discuss best practices for using these functions.

The functions i discussed in my previous post and backticks operators are good when you want to run an external program just to get the output produced by the external program and the input required by the command can be supplied by using comman line parameters. But if you want to run an external program interactively, then you need to use following functions :

1) proc_open function

proc_open function takes three compulsory parameters. First parameter is the name of the external command to run. Second is an array which contains specifications of file descriptors, that is how do you want to connect with the external command's stdin, stdout, and stderr. Index 0 has specification for stdin, 1 for stdout and 2 for stderr. You can also specify more file descriptors which will be passed to external command and can be used for communication. The two pipe types which you can use are pipe and file. Third variable is passed as a reference which is set to be an array of file pointers corresponding to the descriptors specified in the second parameter. Optionally, you can also provide cwd, env and other options. For example, after running the following code :

<?php

 $proc = proc_open('wc', 
                   array(
                    0 => array('pipe', 'r'),
                    1 => array('pipe', 'w'),
                    2 => array('file', 'temp/log.txt', 'a')),
                   $fp_array);
  
 $input = <<<EDT
This is first line.
This is second line.
EDT;
 
 fwrite($fp_array[0], $input);
 fclose($fp_array[0]);
  
 $output = stream_get_contents($fp_array[1]);
 
 fclose($fp_array[1]); 
 proc_close($proc);
 
 echo $output;               
  
?>

we will get following output :

1 8 40

Notice how we provided input to the external command by writing data to the stdin pipe of the external command and retrived command output by reading data from the stdout pipe of the external command. Be careful to close down connecting pipe file pointers before closing the process with proc_close function, otherwise a deadlock will be created and php will hang.

2) popen function

popen function also enables you to execute external program but if you use this function to run an external command then communication with the external command is unidirectional. That is you either write to external command's stdin or read from external command's stdout. popen function accepts two parameters. First parameter is the name of the external command to run and second is the mode of communication. For example, the following code will display the list of files in curent directory :

<?php

 $fp = popen('ls -l', 'r');
 $output = stream_get_contents($fp);
 pclose($fp);
 
 echo $output;               
  
?>

Notice how we used the pipe file pointer returned by popen to read the command output. Once the output is read, we close it with pclose function.

You can also use any one of these functions (except popen function) and backticks operator to run external progam which will run in background. To do it redirect standard input and standard stream to a file and send the command to background. For example,

<?php

  shell_exec('./test_command > /dev/null 2> /dev/null &');
  
  echo 'Command executed successfully!';   
  
?>

this code will execute external command test_command in the background and its stdout and stderr is redirected to /dev/null.

Security

Now, while using these functions or backticks operator, best thing to do would be to not pass any input taken from the user using command line parameters. But if you can't avoid it then you should using following two functions to make sure that the user giving input doesn't tricks shell into executing arbitrary commands:

1) escapeshellarg function

This function is used for escaping single arguments coming from user input. It puts single quotes around strings and escapes any existing single quotes in the string allowing you to safely pass a string to the shell command.

2) escapeshellcmd function

This function is used for escaping meta characters in the complete command. On *nix based platform following characters are escaped : #&;`|*?~<>^()[]{}$\, \x0A and \xFF. single quote and double quotes are escaped only if they are not present in pairs. On windows platform, preceding characters alongiwht % are replaced by space.

If you have safe_mode option enabled in php.ini, then command strings are automatically escaped with escapeshellcmd function.