Accessing the Command Line From PHP

This tutorial will explain the different methods of accessing the system command line from a PHP script. Being able to run external programs can come in handy, and fortunately there are multiple functions that will do this. We will explain the differences betweeen these so you can choose the best one for your purpose. The functions covered are exec(), system(), passthru(), and shell_exec(), as well as escapeshellcmd() and escapeshellarg(). See the manual for more information on these functions.

Important Notes

• Make sure to escape any user-supplied input before passing it to these functions. This is accomplished using the escapeshellcmd() and escapeshellarg() functions, which are explained below. This is very important for security reasons.
• With safe_mode enabled, commands are automatically escaped with escapeshellcmd(). Also, shell_exec() and the "backtick operator" are disabled with safe_mode.
• With safe_mode enabled, only files within the safe_mode_exec_dir can be executed.
• If you use these functions to start a program, PHP will hang until the program ends unless you redirect the output of the program.

Escaping Input

• Use escapeshellcmd() to escape all special characters the can be used in the command line. Use this on any user supplied or potentially dangerous input before using it as part of a command on the shell. This will prevent people from tricking the script into running extra commands.
• Use escapeshellarg() to escape a string to be used as a shell argument. This adds single quotes around the string and escapes any unpaired single quotes. This turns any string into a safe shell argument.

shell_exec

The shell_exec() function is the most basic way to run commands from PHP. It accepts the command as the single argument and returns the entire output as a string. It behaves exactly like the "backtick operator" (``).

string shell_exec ( string $cmd )

or

$output = `cmd`

• cmd: the shell command as a string
• Returns: the output from the shell as a string

When to Use

• You want to simply run the command and see/store the entire output

Example

This will display a list of files in the current directory.

system

The system() function is also a simple way to access the command line. It accepts the command as the first argument and a variable to store the return status of the program as an optional second argument. It only returns the last line if the output.

string system ( string $command [, int &$return_var ] )

• command: the shell command as a string
• return_var: optional; a variable to store the return status of the command
• Returns: the last line of output from the shell as a string

When to Use

• You want to simply run the command and optionally
• You want to know the return value
• You only need to see the last line of the output

Example

This will display the name of the current user if the command was successful.

passthru

The passthru() function is similar to the system() function, but passes the output from the command directly to the client browser. This is useful when the program produces binary data such as an image.

void passthru ( string $command [, int &$return_var ] )

• command: the shell command as a string
• return_var: optional; a variable to store the return status of the command

When to Use

• You want to run a program and pass binary output directly to the browser

Example

This will read somefile.gif and send it directly to the browser.

exec

The exec() function provides the most control out of these. It takes the command in the first argument and stores the output and return value in the optional second and third arguments respectively.

string exec ( string $command [, array &$output [, int &$return_var ]] )

• command: the shell command as a string
• output: optional; a variable to store the output as an array of lines
• return_var: optional; a variable to store the return status of the command
• Returns: the last line of output from the shell as a string

When to Use

• You want to simply run a program and optionally
• You want to have access the the full output and/or return status
• You also want easy access to the last line of output

Example

This will ping the supplied host 3 times and store the output in the $out array.

Conclusion

The two functions you really need to know are exec() and passthru(), since these two allow you to do everything that the other functions can do combined. You need to keep security in mind when using these since direct access to the system command line opens up many possibilities. Using the two escape functions will protect you from attacks or unexpected results. Also, keep in mind that safe_mode affects the behavior of these functions (see the notes above for details).

Similar Posts:

• PHP in the Shell
• Using SSH in PHP
• Fetch Twitter Updates in PHP

Author: Steve

Steve is the owner of UlraMega Tech. He is a freelance Web designer and developer who specializes in PHP and AJAX development.