Javascript debugger
Website design
↑
As of version 4.3.0, PHP supports a new
SAPI
type (Server Application Programming Interface)
named CLI
which means Command Line
Interface. As the name implies, this SAPI
type
main focus is on developing shell (or desktop as well) applications with
PHP. There are quite a few differences between the
CLI SAPI
and other SAPI
s which are
explained in this chapter. It's worth mentioning
that CLI
and CGI
are different
SAPI's although they do share many of the same behaviors.
The CLI SAPI
was released for the first time with
PHP 4.2.0, but was still experimental and had
to be explicitly enabled with --enable-cli
when running
./configure. Since PHP 4.3.0 the
CLI SAPI
is no longer experimental and the option
--enable-cli
is on by default. You may use
--disable-cli
to disable it.
As of PHP 4.3.0, the name, location and existence of the CLI/CGI binaries
will differ depending on how PHP is installed on your system. By default
when executing make, both the CGI and CLI are built and
placed as sapi/cgi/php
and sapi/cli/php
respectively, in your PHP source directory. You will note that both are
named php. What happens during make install depends on
your configure line. If a module SAPI is chosen during configure, such as apxs, or the
--disable-cgi
option is used, the CLI is copied to
{PREFIX}/bin/php
during make install
otherwise the CGI is placed there. So, for example, if --with--apxs
is in your configure line then the CLI is copied to
{PREFIX}/bin/php
during make
install. If you want to override the installation of the CGI
binary, use make install-cli after make
install. Alternatively you can specify
--disable-cgi
in your configure line.
Because both --enable-cli
and
--enable-cgi
are enabled by default,
simply having --enable-cli
in your
configure line does not necessarily mean the CLI will be copied as
{PREFIX}/bin/php
during make install.
The Windows packages between PHP 4.2.0 and PHP 4.2.3 distributed the CLI as
php-cli.exe
, living in the same folder as the CGI
php.exe
. Starting with PHP 4.3.0 the Windows package
distributes the CLI as php.exe
in a separate folder
named cli
, so cli/php.exe
. Starting with PHP 5, the CLI is distributed in the main folder,
named php.exe
. The CGI version is distributed as
php-cgi.exe
.
As of PHP 5, a new php-win.exe
file is distributed.
This is equal to the CLI version, except that php-win doesn't output
anything and thus provides no console (no "dos box" appears on the screen).
This behavior is similar to php-gtk. You should configure with
--enable-cli-win32
.
From a shell, typing php -v will tell you
whether php
is CGI or CLI. See also the function
php_sapi_name() and the constant
PHP_SAPI
.
A Unix man
ual page was added in PHP 4.3.2. You may
view this by typing man php in your shell environment.
Remarkable differences of the CLI SAPI
compared to other
SAPI
s:
Unlike the CGI SAPI
, no headers are written to the
output.
Though the CGI SAPI
provides a way to suppress HTTP
headers, there's no equivalent switch to enable them in the CLI
SAPI
.
CLI is started up in quiet mode by default, though the -q
and --no-header
switches are kept for compatibility so
that you can use older CGI scripts.
It does not change the working directory to that of the script.
(-C
and --no-chdir
switches kept for
compatibility)
Plain text error messages (no HTML formatting).
There are certain php.ini
directives which are overridden by the CLI
SAPI
because they do not make sense in shell environments:
php.ini
directivesDirective | CLI SAPI default value | Comment |
---|---|---|
html_errors | FALSE |
It can be quite hard to read the error message in your shell when
it's cluttered with all those meaningless HTML
tags, therefore this directive defaults to FALSE .
|
implicit_flush | TRUE | It is desired that any output coming from print(), echo() and friends is immediately written to the output and not cached in any buffer. You still can use output buffering if you want to defer or manipulate standard output. |
max_execution_time | 0 (unlimited) | Due to endless possibilities of using PHP in shell environments, the maximum execution time has been set to unlimited. Whereas applications written for the web are often executed very quickly, shell application tend to have a much longer execution time. |
register_argc_argv | TRUE |
Because this setting is
As of PHP 4.3.0, the PHP variables |
These directives cannot be initialized with another value from the
configuration file php.ini
or a custom one (if specified). This is a
limitation because those default values are applied after all
configuration files have been parsed. However, their value can be changed
during runtime (which does not make sense for all of those directives,
e.g. register_argc_argv).
To ease working in the shell environment, the following constants are defined:
Constant | Description |
---|---|
STDIN |
An already opened stream to <?php
If you want to read single line from <?php |
STDOUT |
An already opened stream to <?php |
STDERR |
An already opened stream to <?php
|
Given the above, you don't need to open e.g. a stream for
stderr
yourself but simply use the constant instead of
the stream resource:
php -r 'fwrite(STDERR, "stderr\n");'
You do not need to explicitly close these streams, as they are closed automatically by PHP when your script ends.
The CLI SAPI
does not change the current directory to the directory
of the executed script!
Example showing the difference to the CGI SAPI
:
<?php
// Our simple test application named test.php
echo getcwd(), "\n";
?>
When using the CGI
version, the output is:
$ pwd
/tmp
$ php -q another_directory/test.php
/tmp/another_directory
This clearly shows that PHP changes its current directory to the one of the executed script.
Using the CLI SAPI
yields:
$ pwd
/tmp
$ php -f another_directory/test.php
/tmp
This allows greater flexibility when writing shell tools in PHP.
The CGI SAPI
supports this CLI SAPI
behaviour by means of the -C
switch when run from the
command line.
The list of command line options provided by the PHP
binary can be queried anytime by running PHP with the
-h
switch:
Usage: php [options] [-f] <file> [--] [args...]
php [options] -r <code> [--] [args...]
php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
php [options] -- [args...]
php [options] -a
-a Run interactively
-c <path>|<file> Look for php.ini file in this directory
-n No php.ini file will be used
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-f <file> Parse and execute <file>.
-h This help
-i PHP information
-l Syntax check only (lint)
-m Show compiled in modules
-r <code> Run PHP <code> without using script tags <?..?>
-B <begin_code> Run PHP <begin_code> before processing input lines
-R <code> Run PHP <code> for every input line
-F <file> Parse and execute <file> for every input line
-E <end_code> Run PHP <end_code> after processing all input lines
-H Hide any passed arguments from external tools.
-s Display colour syntax highlighted source.
-v Version number
-w Display source with stripped comments and whitespace.
-z <file> Load Zend extension <file>.
args... Arguments passed to script. Use -- args when first argument
starts with - or script is read from stdin
--ini Show configuration file names
--rf <name> Show information about function <name>.
--rc <name> Show information about class <name>.
--re <name> Show information about extension <name>.
--ri <name> Show configuration for extension <name>.
The CLI SAPI
has three different ways of getting the
PHP code you want to execute:
Telling PHP to execute a certain file.
php my_script.php
php -f my_script.php
Both ways (whether using the -f
switch or not) execute
the file my_script.php
. You can choose any file to
execute - your PHP scripts do not have to end with the
.php
extension but can have any name or extension
you wish.
Pass the PHP code to execute directly on the command line.
php -r 'print_r(get_defined_constants());'
Special care has to be taken in regards of shell variable substitution and quoting usage.
Read the example carefully, there are no beginning or ending tags! The
-r
switch simply does not need them. Using them will
lead to a parser error.
Provide the PHP code to execute via standard input
(stdin
).
This gives the powerful ability to dynamically create PHP code and feed it to the binary, as shown in this (fictional) example:
$ some_application | some_filter | php | sort -u >final_output.txt
You cannot combine any of the three ways to execute code.
Like every shell application, the PHP binary
accepts a number of arguments but your PHP script can
also receive arguments. The number of arguments which can be passed to your script
is not limited by PHP (the shell has a certain size limit
in the number of characters which can be passed; usually you won't hit this
limit). The arguments passed to your script are available in the global
array $argv
. The zero index always contains the script
name (which is -
in case the PHP code
is coming from either standard input or from the command line switch
-r
). The second registered global variable is
$argc
which contains the number of elements in the
$argv
array (not the
number of arguments passed to the script).
As long as the arguments you want to pass to your script do not start with
the -
character, there's nothing special to watch out
for. Passing an argument to your script which starts with a
-
will cause trouble because PHP
itself thinks it has to handle it. To prevent this, use the argument list
separator --
. After this separator has been parsed by
PHP, every argument following it is passed
untouched to your script.
# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]
# This will pass the '-h' argument to your script and prevent PHP from showing it's usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
}
However, there's another way of using PHP for shell
scripting. You can write a script where the first line starts with
#!/usr/bin/php
. Following this you can place
normal PHP code included within the PHP
starting and end tags. Once you have set the execution attributes of the file
appropriately (e.g. chmod +x test) your script can be
executed like a normal shell or perl script:
#!/usr/bin/php
<?php
var_dump($argv);
?>
Assuming this file is named test
in the current
directory, we can now do the following:
$ chmod +x test
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./test"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
}
As you see, in this case no care needs to be taken when passing parameters
which start with -
to your script.
Long options are available since PHP 4.3.3.
Option | Long Option | Description |
---|---|---|
-a | --interactive |
Runs PHP interactively. If you compile PHP with the Readline extension (which is not
available on Windows), you'll have a nice shell, including a
completion feature (e.g. you can start typing a variable name, hit the
TAB key and PHP completes its name) and a typing history that can be
accessed using the arrow keys. The history is saved in the
Note: Files included through auto_prepend_file and auto_append_file are parsed in this mode but with some restrictions - e.g. functions have to be defined before called. Note: Autoloading is not available if using PHP in CLI interactive mode.
|
-c | --php-ini |
This option can either specify a directory where to look for
$ php -c /custom/directory/ my_script.php If you don't specify this option, file is searched in default locations. |
-n | --no-php-ini |
Ignore |
-d | --define |
This option allows you to set a custom value for any of the configuration
directives allowed in -d configuration_directive[=value] Examples (lines are wrapped for layout reasons): # Omitting the value part will set the given configuration directive to "1"
|
-e | --profile-info |
Activate the extended information mode, to be used by a debugger/profiler. |
-f | --file |
Parses and executed the given filename to the |
-h and -? | --help and --usage | With this option, you can get information about the actual list of command line options and some one line descriptions about what they do. |
-i | --info |
This command line option calls phpinfo(), and prints
out the results. If PHP is not working correctly, it is
advisable to use php -i and see whether any error
messages are printed out before or in place of the information tables.
Beware that when using the CGI mode the output is in HTML
and therefore quite huge.
|
-l | --syntax-check |
This option provides a convenient way to only perform a syntax check
on the given PHP code. On success, the text
This option won't find fatal errors (like undefined functions). Use
Note:
This option does not work together with the
|
-m | --modules |
Using this option, PHP prints out the built in (and loaded) PHP and Zend modules: $ php -m
|
-r | --run |
This option allows execution of PHP right from
within the command line. The PHP start and end tags
( Note: Care has to be taken when using this form of PHP to not collide with command line variable substitution done by the shell. Example showing a parser error $ php -r "$foo = get_defined_constants();"
The problem here is that the sh/bash performs variable substitution
even when using double quotes $ php -r " = get_defined_constants();"
The correct way would be to use single quotes $ php -r '$foo = get_defined_constants(); var_dump($foo);' If you are using a shell different from sh/bash, you might experience further issues. Feel free to open a bug report at » http://bugs.php.net/. One can still easily run into troubles when trying to get shell variables into the code or using backslashes for escaping. You've been warned. Note:
Note: This option is meant for a very basic stuff. Thus some configuration directives (e.g. auto_prepend_file and auto_append_file) are ignored in this mode.
|
-B | --process-begin |
PHP code to execute before processing stdin. Added in PHP 5. |
-R | --process-code |
PHP code to execute for every input line. Added in PHP 5.
There are two special variables available in this mode:
|
-F | --process-file |
PHP file to execute for every input line. Added in PHP 5. |
-E | --process-end |
PHP code to execute after processing the input. Added in PHP 5. Example 10.2. Using the |
-s | --syntax-highlight and --syntax-highlight |
Display colour syntax highlighted source.
This option uses the internal mechanism to parse the file and produces
a Note:
This option does not work together with the
|
-v | --version |
Writes the PHP, PHP SAPI, and Zend version to standard output, e.g. $ php -v
|
-w | --strip |
Display source with stripped comments and whitespace. Note:
This option does not work together with the
|
-z | --zend-extension |
Load Zend extension. If only a filename is given, PHP tries to load
this extension from the current default library path on your system
(usually specified |
--ini |
Shows configuration file names and scanned directories. Available as of PHP 5.2.3. Example 10.3. --ini example$ php --ini
| |
--rf | --rfunction |
Shows information about the given function or class method (e.g. number and name of the parameters). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support. Example 10.4. basic --rf usage$ php --rf var_dump
|
--rc | --rclass |
Show information about the given class (list of constants, properties and methods). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support. Example 10.5. --rc example$ php --rc Directory
|
--re | --rextension |
Show information about the given extension (list of This option is only available if PHP was compiled with Reflection support. Example 10.6. --re example$ php --re json
|
--ri | --rextinfo |
Shows the configuration information for the given extension (the same information that is returned by phpinfo()). Available as of PHP 5.2.2. The core configuration information are available using "main" as extension name. Example 10.7. --ri example$ php --ri date
|
The PHP executable can be used to run PHP scripts absolutely independent
from the web server. If you are on a Unix system, you should add a special
first line to your PHP script, and make it executable, so the system will
know, what program should run the script. On a Windows platform you can
associate php.exe
with the double click option of the
.php
files, or you can make a batch
file to run the script through PHP. The first line added to the script to
work on Unix won't hurt on Windows, so you can write cross platform programs
this way. A simple example of writing a command line PHP program can be
found below.
#!/usr/bin/php
<?php
if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>
This is a command line PHP script with one option.
Usage:
<?php echo $argv[0]; ?> <option>
<option> can be some word you would like
to print out. With the --help, -help, -h,
or -? options, you can get this help.
<?php
} else {
echo $argv[1];
}
?>
In the script above, we used the special first line to indicate
that this file should be run by PHP. We work with a CLI version
here, so there will be no HTTP header printouts. There are two
variables you can use while writing command line applications with
PHP: $argc
and $argv
. The
first is the number of arguments plus one (the name of the script
running). The second is an array containing the arguments, starting
with the script name as number zero ($argv[0]
).
In the program above we checked if there are less or more than one
arguments. Also if the argument was --help
,
-help
, -h
or -?
,
we printed out the help message, printing the script name dynamically.
If we received some other argument we echoed that out.
If you would like to run the above script on Unix, you need to make it executable, and simply call it as script.php echothis or script.php -h. On Windows, you can make a batch file for this task:
@C:\php\php.exe script.php %1 %2 %3 %4
Assuming you named the above program
script.php
, and you have your
CLI php.exe
in
C:\php\php.exe
this batch file
will run it for you with your added options:
script.bat echothis or
script.bat -h.
See also the Readline extension documentation for more functions you can use to enhance your command line applications in PHP.