Command Line Interface (CLI)
Arguments are passed to the program in a manner similar to most C-style languages.
$argc is an integer containing the number of arguments including the program name, and
$argv is an array containing arguments to the program. The first element of
$argv is the name of the program.
Calling the above application with
php example.php foo bar (where example.php contains the above code) will result in the following output:
You called the program example.php with 2 arguments
Argument 1 is foo
Argument 2 is bar
$argv are global variables, not superglobal variables. They must be imported into the local scope using the
global keyword if they are needed in a function.
This example shows the how arguments are grouped when escapes such as
\ are used.
If the PHP script is run using
Or code piped into STDIN of
Behavioural differences on the command line
When running from the CLI, PHP exhibits some different behaviours than when run from a web server. These differences should be kept in mind, especially in the case where the same script might be run from both environments.
- No directory change When running a script from a web server, the current working directory is always that of the script itself. The code
require("./stuff.inc");assumes the file is in the same directory as the script. On the command line, the current working directory is the directory you're in when you call the script. Scripts that are going to be called from the command line should always use absolute paths. (Note the magic constants
__FILE__continue to work as expected, and return the location of the script.)
- No output buffering The
true, respectively. Buffering is still available, but must be explicitly enabled, otherwise output will always be displayed in real time.
- No time limit The
max_execution_timeis set to zero, so scripts will not time out by default.
- No HTML errors In the event you have enabled the
html_errors, it will be ignored on the command line.
php.inican be loaded. When you are using php from cli it can use different
php.inithan web server do. You can know what file is using by running
Edge Cases of getopt()
This example shows the behaviour of
getopt when the user input is uncommon:
getopt.phpShell command line
From this example, it can be seen that:
- Individual options (no colon) always carry a boolean value of
- If an option is repeated, the respective value in the output of
getoptwill become an array.
- Required argument options (one colon) accept one space or no space (like optional argument options) as separator
- After one argument that cannot be mapped into any options, the options behind will not be mapped either.
Handling Program Options
Program options can be handled with the
getopt() function. It operates with a similar syntax to the POSIX
getopt command, with additional support for GNU-style long options.
This script can be tested like so:
Note the last method will not work because
-v 5 is not valid.
Note: As of PHP 5.3.0,
getoptis OS independent, working also on Windows.
Input and Output Handling
When run from the CLI, the constants STDIN, STDOUT, and STDERR are predefined. These constants are file handles, and can be considered equivalent to the results of running the following commands:
The constants can be used anywhere a standard file handle would be:
The builtin stream addresses referenced earlier (
php://stderr) can be used in place of filenames in most contexts:
As an alternative, you can also use readline() for input, and you can also use echo or print or any other string printing functions for output.
Restrict script execution to command line
php_sapi_name() and the constant
PHP_SAPI both return the type of interface (Server API) that is being used by PHP. They can be used to restrict the execution of a script to the command line, by checking whether the output of the function is equal to
drupal_is_cli() function is an example of a function that detects whether a script has been executed from the command line:
The exit construct can be used to pass a return code to the executing environment.
By default an exit code of
0 will be returned if none is provided, i.e.
exit is the same as
exit is not a function, parentheses are not required if no return code is being passed.
Return codes must be in the range of 0 to 254 (255 is reserved by PHP and should not be used). By convention, exiting with a return code of
0 tells the calling program that the PHP script ran successfully. Use a non-zero return code to tell the calling program that a specific error condition occurred.
Running built-in web server
As from version 5.4, PHP comes with built-in server. It can be used to run application without need to install other http server like nginx or apache. Built-in server is designed only in controller environment for development and testing purposes.
It can be run with command php -S :
To test it create
index.php file containing
and run command
php -S localhost:8080
Now yout should be able to see content in browser. To check this, navigate to
Every access should result in log entry written to terminal
Running your script
On either Linux/UNIX or Windows, a script can be passed as an argument to the PHP executable, with that script's options and arguments following:
bar as arguments to
On Linux/UNIX, the preferred method of running scripts is to use a shebang (e.g.
#!/usr/bin/env php) as the first line of a file, and set the executable bit on the file. Assuming the script is in your path, you can then call it directly:
/usr/bin/env php makes the PHP executable to be found using the PATH. Following how PHP is installed, it might not be located at the same place (such as
env which is commonly available from
On Windows, you could have the same result by adding the PHP's directory and your script to the PATH and editing PATHEXT to allow
.php to be detected using the PATH. Another possibility is to add a file named
example.cmd in the same directory as your PHP script and write this line into it:
Or, if you added PHP's directory into the PATH, for convenient use: