mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
91e836093c
as UNIX is a registered trademark by the Open Group. References to UNIX were left in where it made sense, like example outputs, and so forth. You can read the Trademark User Guide for "UNIX" at: http://www.unix.org/tmug2.ps or http://www.unix.org/tmug2.pdf git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@147067 c90b9560-bf6c-de11-be94-00142212c4b1
1133 lines
37 KiB
XML
1133 lines
37 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.26 $ -->
|
|
<chapter id="features.commandline">
|
|
<title>Using PHP from the command line</title>
|
|
<!-- NEW DOCUMENTATION STARTS -->
|
|
<para>
|
|
As of version 4.3.0, <literal>PHP</literal> supports a new
|
|
<literal>SAPI</literal> type (Server Application Programming Interface)
|
|
named <literal>CLI</literal> which means <emphasis>Command Line
|
|
Interface</emphasis>. As the name implies, this <literal>SAPI</literal> type
|
|
main focus is on developing shell (or desktop as well) applications with
|
|
<literal>PHP</literal>. There are quite a few differences between the
|
|
<literal>CLI SAPI</literal> and other <literal>SAPI</literal>s which are
|
|
explained in this chapter. It's worth mentioning
|
|
that <literal>CLI</literal> and <literal>CGI</literal> are different
|
|
SAPI's although they do share many of the same behaviors.
|
|
</para>
|
|
<para>
|
|
The <literal>CLI SAPI</literal> was released for the first time with
|
|
<literal>PHP 4.2.0</literal>, but was still experimental and had
|
|
to be explicitly enabled with <literal>--enable-cli</literal> when running
|
|
<literal>./configure</literal>. Since <literal>PHP 4.3.0</literal> the
|
|
<literal>CLI SAPI</literal> is no longer experimental and the option
|
|
<literal>--enable-cli</literal> is on by default. You may use
|
|
<literal>--disable-cli</literal> to disable it.
|
|
</para>
|
|
<para>
|
|
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 <literal>make</literal>, both the CGI and CLI are built and
|
|
placed as <literal>sapi/cgi/php</literal> and <literal>sapi/cli/php</literal>
|
|
respectively, in your PHP source directory. You will note that both are
|
|
named <literal>php</literal>. What happens during <literal>make
|
|
install</literal> depends on your configure
|
|
line. If a module SAPI is chosen during configure, such as apxs, or the
|
|
<literal> --disable-cgi</literal> option is used, the CLI is copied to
|
|
<literal>{PREFIX}/bin/php</literal> during <literal>make install</literal>
|
|
otherwise the CGI is placed there. So, for example, if <literal>--with--apxs
|
|
</literal> is in your configure line then the CLI is copied to
|
|
<literal>{PREFIX}/bin/php</literal> during <literal>make
|
|
install</literal>. If you want to override the installation of the CGI
|
|
binary, use <literal>make install-cli</literal> after <literal>make
|
|
install</literal>. Alternatively you can specify <literal>--disable-cgi
|
|
</literal> in your configure line.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
Because both <literal>--enable-cli</literal> and <literal>
|
|
--enable-cgi</literal> are enabled by default, simply having
|
|
<literal>--enable-cli</literal> in your configure line does
|
|
not necessarily mean the CLI will be copied as <literal>
|
|
{PREFIX}/bin/php</literal> during <literal>make install</literal>.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
The windows packages between PHP 4.2.0 and PHP 4.2.3 distributed the CLI as
|
|
<filename>php-cli.exe</filename>, living in the same folder as the CGI
|
|
<filename>php.exe</filename>. Starting with PHP 4.3.0 the windows package
|
|
distributes the CLI as <filename>php.exe</filename> in a separate folder
|
|
named <literal>cli</literal>, so <literal>cli/php.exe</literal>.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<title>What SAPI do I have?</title>
|
|
<para>
|
|
From a shell, typing <literal>php -v</literal> will tell you
|
|
whether <literal>php</literal> is CGI or CLI. See also the function
|
|
<function>php_sapi_name</function> and the constant <constant>
|
|
PHP_SAPI</constant>.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
A Unix <literal>man</literal>ual page was added in PHP 4.3.2. You may
|
|
view this by typing <literal>man php</literal> in your shell environment.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
Remarkable differences of the <literal>CLI SAPI</literal> compared to other
|
|
<literal>SAPI</literal>s:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Unlike the <literal>CGI SAPI</literal>, no headers are written to the
|
|
output.
|
|
</para>
|
|
<para>
|
|
Though the <literal>CGI SAPI</literal> provides a way to suppress HTTP
|
|
headers, there's no equivalent switch to enable them in the <literal>CLI
|
|
SAPI</literal>.
|
|
</para>
|
|
<para>
|
|
CLI is started up in quiet mode by default, though the <literal>-q</literal>
|
|
and <literal>--no-header</literal> switches are kept for compatibility so that you can use older CGI scripts.
|
|
</para>
|
|
<para>
|
|
It does not change the working directory to that of the script.
|
|
(<literal>-C</literal> and <literal>--no-chdir</literal> switches kept for compatibility)
|
|
</para>
|
|
<para>
|
|
Plain text error messages (no HTML formatting).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
There are certain &php.ini; directives which are overridden by the <literal>CLI
|
|
SAPI</literal> because they do not make sense in shell environments:
|
|
</para>
|
|
<para>
|
|
<table>
|
|
<title>Overridden &php.ini; directives</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Directive</entry>
|
|
<entry><literal>CLI SAPI</literal> default value</entry>
|
|
<entry>Comment</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><link linkend="ini.html-errors">html_errors</link></entry>
|
|
<entry>&false;</entry>
|
|
<entry>
|
|
It can be quite hard to read the error message in your shell when
|
|
it's cluttered with all those meaningless <literal>HTML</literal>
|
|
tags, therefore this directive defaults to &false;.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
It is desired that any output coming from
|
|
<function>print</function>, <function>echo</function> and friends is
|
|
immediately written to the output and not cached in any buffer. You
|
|
still can use <link linkend="ref.outcontrol">output buffering</link>
|
|
if you want to defer or manipulate standard output.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.max-execution-time">max_execution_time</link></entry>
|
|
<entry>0 (unlimited)</entry>
|
|
<entry>
|
|
Due to endless possibilities of using <literal>PHP</literal> 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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.register-argc-argv">register_argc_argv</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
<para>
|
|
Because this setting is &true; you will always have access to
|
|
<emphasis>argc</emphasis> (number of arguments passed to the
|
|
application) and <emphasis>argv</emphasis> (array of the actual
|
|
arguments) in the <literal>CLI SAPI</literal>.
|
|
</para>
|
|
<para>
|
|
As of PHP 4.3.0, the <literal>PHP</literal> variables <varname>$argc</varname>
|
|
and <varname>$argv</varname> are registered and filled in with the appropriate
|
|
values when using the <literal>CLI SAPI</literal>. Prior to this version,
|
|
the creation of these variables behaved as they do in
|
|
<literal>CGI</literal> and <literal>MODULE</literal> versions
|
|
which requires the PHP directive
|
|
<link linkend="ini.register-globals">register_globals</link> to
|
|
be <emphasis>on</emphasis>. Regardless of version or register_globals
|
|
setting, you can always go through either
|
|
<link linkend="reserved.variables.server">$_SERVER</link> or
|
|
<varname>$HTTP_SERVER_VARS</varname>. Example:
|
|
<varname>$_SERVER['argv']</varname>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
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. <link linkend="ini.register-argc-argv">register_argc_argv</link>).
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
To ease working in the shell environment, the following constants
|
|
are defined:
|
|
<table>
|
|
<title>CLI specific Constants</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Constant</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><constant>STDIN</constant></entry>
|
|
<entry>
|
|
An already opened stream to <literal>stdin</literal>. This saves
|
|
opening it with
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$stdin = fopen('php://stdin', 'r');
|
|
]]>
|
|
</programlisting>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>STDOUT</constant></entry>
|
|
<entry>
|
|
An already opened stream to <literal>stdout</literal>. This saves
|
|
opening it with
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$stdout = fopen('php://stdout', 'w');
|
|
]]>
|
|
</programlisting>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>STDERR</constant></entry>
|
|
<entry>
|
|
An already opened stream to <literal>stderr</literal>. This saves
|
|
opening it with
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$stderr = fopen('php://stderr', 'w');
|
|
]]>
|
|
</programlisting>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<para>
|
|
Given the above, you don't need to open e.g. a stream for
|
|
<literal>stderr</literal> yourself but simply use the constant instead of
|
|
the stream resource:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
php -r 'fwrite(STDERR, "stderr\n");'
|
|
]]>
|
|
</programlisting>
|
|
You do not need to explicitly close these streams, as they are closed
|
|
automatically by <literal>PHP</literal> when your script ends.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <literal>CLI SAPI</literal> does <emphasis
|
|
role="strong">not</emphasis> change the current directory to the directory
|
|
of the executed script!
|
|
</para>
|
|
<para>
|
|
Example showing the difference to the <literal>CGI SAPI</literal>:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* Our simple test application named test.php*/
|
|
echo getcwd(), "\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
When using the <literal>CGI</literal> version, the output is:
|
|
<screen>
|
|
<![CDATA[
|
|
$ pwd
|
|
/tmp
|
|
|
|
$ php -q another_directory/test.php
|
|
/tmp/another_directory
|
|
]]>
|
|
</screen>
|
|
This clearly shows that <literal>PHP</literal> changes its current
|
|
directory to the one of the executed script.
|
|
</para>
|
|
<para>
|
|
Using the <literal>CLI SAPI</literal> yields:
|
|
<screen>
|
|
<![CDATA[
|
|
$ pwd
|
|
/tmp
|
|
|
|
$ php -f another_directory/test.php
|
|
/tmp
|
|
]]>
|
|
</screen>
|
|
This allows greater flexibility when writing shell tools in
|
|
<literal>PHP</literal>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The <literal>CGI SAPI</literal> supports the <literal>CLI SAPI</literal>
|
|
behaviour by means of the <literal>-C</literal> switch when run from the
|
|
command line.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The list of command line options provided by the <literal>PHP</literal>
|
|
binary can be queried anytime by running <literal>PHP</literal> with the
|
|
<literal>-h</literal> switch:
|
|
<screen>
|
|
<![CDATA[
|
|
Usage: php [options] [-f] <file> [args...]
|
|
php [options] -r <code> [args...]
|
|
php [options] [-- args...]
|
|
-s Display colour syntax highlighted source.
|
|
-w Display source with stripped comments and whitespace.
|
|
-f <file> Parse <file>.
|
|
-v Version number
|
|
-c <path>|<file> Look for php.ini file in this directory
|
|
-a Run interactively
|
|
-d foo[=bar] Define INI entry foo with value 'bar'
|
|
-e Generate extended information for debugger/profiler
|
|
-z <file> Load Zend extension <file>.
|
|
-l Syntax check only (lint)
|
|
-m Show compiled in modules
|
|
-i PHP information
|
|
-r <code> Run PHP <code> without using script tags <?..?>
|
|
-h This help
|
|
|
|
args... Arguments passed to script. Use -- args when first argument
|
|
starts with - or script is read from stdin
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The <literal>CLI SAPI</literal> has three different ways of getting the
|
|
<literal>PHP</literal> code you want to execute:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Telling <literal>PHP</literal> to execute a certain file.
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
php my_script.php
|
|
|
|
php -f my_script.php
|
|
]]>
|
|
</screen>
|
|
Both ways (whether using the <literal>-f</literal> switch or not) execute
|
|
the file <filename>my_script.php</filename>. You can choose any file to
|
|
execute - your <literal>PHP</literal> scripts do not have to end with the
|
|
<filename>.php</filename> extension but can have any name or extension
|
|
you wish.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Pass the <literal>PHP</literal> code to execute directly on the command
|
|
line.
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
php -r 'print_r(get_defined_constants());'
|
|
]]>
|
|
</screen>
|
|
Special care has to be taken in regards of shell variable substitution and
|
|
quoting usage.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Read the example carefully, there are no beginning or ending tags! The
|
|
<literal>-r</literal> switch simply does not need them. Using them will
|
|
lead to a parser error.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Provide the <literal>PHP</literal> code to execute via standard input
|
|
(<literal>stdin</literal>).
|
|
</para>
|
|
<para>
|
|
This gives the powerful ability to dynamically create
|
|
<literal>PHP</literal> code and feed it to the binary, as shown in this
|
|
(fictional) example:
|
|
<screen>
|
|
<![CDATA[
|
|
$ some_application | some_filter | php | sort -u >final_output.txt
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
You cannot combine any of the three ways to execute code.
|
|
</para>
|
|
<para>
|
|
Like every shell application, the <literal>PHP</literal> binary
|
|
accepts a number of arguments but your <literal>PHP</literal> script can
|
|
also receive arguments. The number of arguments which can be passed to your script
|
|
is not limited by <literal>PHP</literal> (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 <literal>$argv</literal>. The zero index always contains the script
|
|
name (which is <literal>-</literal> in case the <literal>PHP</literal> code
|
|
is coming from either standard input or from the command line switch
|
|
<literal>-r</literal>). The second registered global variable is
|
|
<literal>$argc</literal> which contains the number of elements in the
|
|
<literal>$argv</literal> array (<emphasis role="strong">not</emphasis> the
|
|
number of arguments passed to the script).
|
|
</para>
|
|
<para>
|
|
As long as the arguments you want to pass to your script do not start with
|
|
the <literal>-</literal> character, there's nothing special to watch out
|
|
for. Passing an argument to your script which starts with a
|
|
<literal>-</literal> will cause trouble because <literal>PHP</literal>
|
|
itself thinks it has to handle it. To prevent this, use the argument list
|
|
separator <literal>--</literal>. After this separator has been parsed by
|
|
<literal>PHP</literal>, every argument following it is passed
|
|
untouched to your script.
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
# 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"
|
|
}
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
However, there's another way of using <literal>PHP</literal> for shell
|
|
scripting. You can write a script where the first line starts with
|
|
<literal>#!/usr/bin/php</literal>. Following this you can place
|
|
normal <literal>PHP</literal> code included within the <literal>PHP</literal>
|
|
starting and end tags. Once you have set the execution attributes of the file
|
|
appropriately (e.g. <literal>chmod +x test</literal>) your script can be
|
|
executed like a normal shell or perl script:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
#!/usr/bin/php
|
|
<?php
|
|
var_dump($argv);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
Assuming this file is named <filename>test</filename> in the current
|
|
directory, we can now do the following:
|
|
<screen>
|
|
<![CDATA[
|
|
$ chmod 755 test
|
|
$ ./test -h -- foo
|
|
array(4) {
|
|
[0]=>
|
|
string(6) "./test"
|
|
[1]=>
|
|
string(2) "-h"
|
|
[2]=>
|
|
string(2) "--"
|
|
[3]=>
|
|
string(3) "foo"
|
|
}
|
|
]]>
|
|
</screen>
|
|
As you see, in this case no care needs to be taken when passing parameters
|
|
which start with <literal>-</literal> to your script.
|
|
</para>
|
|
<para>
|
|
Long options are available since PHP 4.3.3.
|
|
<table>
|
|
<title>Command line options</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Long Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>-s</entry>
|
|
<entry>--syntax-highlight</entry>
|
|
<entry>
|
|
<para>
|
|
Display colour syntax highlighted source.
|
|
</para>
|
|
<para>
|
|
This option uses the internal mechanism to parse the file and produces
|
|
a <literal>HTML</literal> highlighted version of it and writes it to
|
|
standard output. Note that all it does it to generate a block of
|
|
<literal><code> [...] </code></literal>
|
|
<literal>HTML</literal> tags, no <literal>HTML</literal> headers.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This option does not work together with the <literal>-r</literal>
|
|
option.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-s</entry>
|
|
<entry>--syntax-highlighting</entry>
|
|
<entry>
|
|
<para>
|
|
Alias of <literal>--syntax-highlight</literal>.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-w</entry>
|
|
<entry>--strip</entry>
|
|
<entry>
|
|
<para>
|
|
Display source with stripped comments and whitespace.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This option does not work together with the <literal>-r</literal>
|
|
option.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-f</entry>
|
|
<entry>--file</entry>
|
|
<entry>
|
|
<para>
|
|
Parses and executed the given filename to the <literal>-f</literal>
|
|
option. This switch is optional and can be left out. Only providing
|
|
the filename to execute is sufficient.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-v</entry>
|
|
<entry>--version</entry>
|
|
<entry>
|
|
<para>
|
|
Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -v
|
|
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
|
|
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-c</entry>
|
|
<entry>--php-ini</entry>
|
|
<entry>
|
|
<para>
|
|
With this option one can either specify a directory where to look for
|
|
&php.ini; or you can specify a custom <literal>INI</literal> file
|
|
directly (which does not need to be named &php.ini;), e.g.:
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -c /custom/directory/ my_script.php
|
|
|
|
$ php -c /custom/directory/custom-file.ini my_script.php
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-n</entry>
|
|
<entry>--no-php-ini</entry>
|
|
<entry>
|
|
<para>
|
|
Ignore php.ini at all. This switch is available since PHP 4.3.0.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-d</entry>
|
|
<entry>--define</entry>
|
|
<entry>
|
|
<para>
|
|
This option allows you to set a custom value for any of the configuration
|
|
directives allowed in &php.ini;. The syntax is:
|
|
<screen>
|
|
<![CDATA[
|
|
-d configuration_directive[=value]
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Examples (lines are wrapped for layout reasons):
|
|
<screen>
|
|
<![CDATA[
|
|
# Omitting the value part will set the given configuration directive to "1"
|
|
$ php -d max_execution_time
|
|
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
|
|
string(1) "1"
|
|
|
|
# Passing an empty value part will set the configuration directive to ""
|
|
php -d max_execution_time=
|
|
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
|
|
string(0) ""
|
|
|
|
# The configuration directive will be set to anything passed after the '=' character
|
|
$ php -d max_execution_time=20
|
|
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
|
|
string(2) "20"
|
|
$ php
|
|
-d max_execution_time=doesntmakesense
|
|
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
|
|
string(15) "doesntmakesense"
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-a</entry>
|
|
<entry>--interactive</entry>
|
|
<entry>
|
|
<para>
|
|
Runs PHP interactively.
|
|
<!--
|
|
mfischer, 20020510: Couldn't come up with a decent useful description
|
|
of the current implementation of the interactive mode.
|
|
-->
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-e</entry>
|
|
<entry>--profile-info</entry>
|
|
<entry>
|
|
<para>
|
|
Generate extended information for debugger/profiler.
|
|
<!--
|
|
mfischer, 20020510: Anyone who can provide more information what it
|
|
really does (even if it's only for developers) ?
|
|
-->
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-z</entry>
|
|
<entry>--zend-extension</entry>
|
|
<entry>
|
|
<para>
|
|
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 <filename>/etc/ld.so.conf</filename> on Linux
|
|
systems). Passing a filename with an absolute path information will
|
|
not use the systems library search path. A relative filename with a
|
|
directory information will tell <literal>PHP</literal> only to try to
|
|
load the extension relative to the current directory.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-l</entry>
|
|
<entry>--syntax-check</entry>
|
|
<entry>
|
|
<para>
|
|
This option provides a convenient way to only perform a syntax check
|
|
on the given <literal>PHP</literal> code. On success, the text
|
|
<literal>No syntax errors detected in <filename></literal> is
|
|
written to standard output and the shell return code is
|
|
<literal>0</literal>. On failure, the text <literal>Errors parsing
|
|
<filename></literal> in addition to the internal parser error
|
|
message is written to standard output and the shell return code is set
|
|
to <literal>255</literal>.
|
|
</para>
|
|
<para>
|
|
This option won't find fatal errors (like undefined functions). Use
|
|
<literal>-f</literal> if you would like to test for fatal errors too.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This option does not work together with the <literal>-r</literal>
|
|
option.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-m</entry>
|
|
<entry>--modules</entry>
|
|
<entry>
|
|
<para>
|
|
Using this option, PHP prints out the built in (and loaded) PHP and
|
|
Zend modules:
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -m
|
|
[PHP Modules]
|
|
xml
|
|
tokenizer
|
|
standard
|
|
session
|
|
posix
|
|
pcre
|
|
overload
|
|
mysql
|
|
mbstring
|
|
ctype
|
|
|
|
[Zend Modules]
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-i</entry>
|
|
<entry>--info</entry>
|
|
<entry>
|
|
This command line option calls <function>phpinfo</function>, and prints
|
|
out the results. If <literal>PHP</literal> is not working correctly, it is
|
|
advisable to use <literal>php -i</literal> and see whether any error
|
|
messages are printed out before or in place of the information tables.
|
|
Beware that the output is in <literal>HTML</literal> and therefore
|
|
quite huge.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-r</entry>
|
|
<entry>--run</entry>
|
|
<entry>
|
|
<para>
|
|
This option allows execution of <literal>PHP</literal> right from
|
|
within the command line. The <literal>PHP</literal> start and end tags
|
|
(<literal><?php</literal> and <literal>?></literal>) are
|
|
<emphasis role="strong">not needed</emphasis> and will cause a parser
|
|
error if present.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Care has to be taken when using this form of <literal>PHP</literal>
|
|
to not collide with command line variable substitution done by the
|
|
shell.
|
|
</para>
|
|
<para>
|
|
Example showing a parser error
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -r "$foo = get_defined_constants();"
|
|
Command line code(1) : Parse error - parse error, unexpected '='
|
|
]]>
|
|
</screen>
|
|
The problem here is that the sh/bash performs variable substitution
|
|
even when using double quotes <literal>"</literal>. Since the
|
|
variable <literal>$foo</literal> is unlikely to be defined, it
|
|
expands to nothing which results in the code passed to
|
|
<literal>PHP</literal> for execution actually reading:
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -r " = get_defined_constants();"
|
|
]]>
|
|
</screen>
|
|
The correct way would be to use single quotes <literal>'</literal>.
|
|
Variables in single-quoted strings are not expanded
|
|
by sh/bash.
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
|
|
array(370) {
|
|
["E_ERROR"]=>
|
|
int(1)
|
|
["E_WARNING"]=>
|
|
int(2)
|
|
["E_PARSE"]=>
|
|
int(4)
|
|
["E_NOTICE"]=>
|
|
int(8)
|
|
["E_CORE_ERROR"]=>
|
|
[...]
|
|
]]>
|
|
</screen>
|
|
If you are using a shell different from sh/bash, you might experience
|
|
further issues. Feel free to open a bug report or send a mail to
|
|
phpdoc@lists.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. <!-- :-) -->
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
<literal>-r</literal> is available in the <emphasis>CLI</emphasis>
|
|
SAPI and not in the <emphasis>CGI</emphasis> SAPI.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-h</entry>
|
|
<entry>--help</entry>
|
|
<entry>
|
|
With this option, you can get information about the actual list of
|
|
command line options and some one line descriptions about what they do.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-?</entry>
|
|
<entry>--usage</entry>
|
|
<entry>
|
|
Alias of <literal>--help</literal>.
|
|
</entry>
|
|
</row>
|
|
<!--
|
|
new, not in PHP 4.3.4, but are in php_cli.c 1.102 or cgi_main.c 1.243
|
|
-b <address:port>|<port> bindpath Bind Path for external FASTCGI Server mode, only CGI, no Windows
|
|
-B <begin_code> process-begin Run PHP <begin_code> before processing input lines
|
|
-R <code> process-code Run PHP <code> for every input line
|
|
-F <file> process-file Parse and execute <file> for every input line
|
|
-E <end_code> process-end Run PHP <end_code> after processing all input lines
|
|
-H hide-args Hide any passed arguments from external tools.
|
|
-g global Define global variables on command line
|
|
-->
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<!-- NEW DOCUMENTATION ENDS -->
|
|
|
|
<!-- OLD DOCUMENTED STARTS
|
|
mfischer, 20020510: I've commented out the start paragraphs of the old
|
|
documentation as it is meant to be replaced by the new one.
|
|
<para>
|
|
The command line options of the PHP executable are useful
|
|
if you would like to debug or test your PHP setup, but they
|
|
can also be handy, if you would like to use PHP for a
|
|
different purpose than web scripting.
|
|
</para>
|
|
<para>
|
|
Note, that you can always direct the output of the PHP
|
|
executable to an external file with the > character,
|
|
so <literal>php -q test.php > test.html</literal> will
|
|
print out the output of <filename>test.php</filename>
|
|
without HTTP headers to the <filename>test.html</filename>
|
|
file in the same directory.
|
|
</para>
|
|
<para>
|
|
You can only use these command line options if you have
|
|
the PHP executable. If you built the server module
|
|
version, and you have no CGI version available on your
|
|
machine, than you have no chance to use these options.
|
|
For Windows users both the PHP executable and the server
|
|
modules are in the binary package, the executable is
|
|
named <filename>php.exe</filename>.
|
|
</para>
|
|
<para>
|
|
This list of command line options is consistent with PHP 4.0.6.
|
|
You can get the actual list and some one line descriptions
|
|
with the <literal>-h</literal> option. The output of
|
|
<literal>php -h</literal> should be something like this:
|
|
<screen>
|
|
<![CDATA[
|
|
Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]}
|
|
-q Quiet-mode. Suppress HTTP Header output.
|
|
-s Display colour syntax highlighted source.
|
|
-f <file> Parse <file>. Implies `-q'
|
|
-v Version number
|
|
-C Do not chdir to the script's directory
|
|
-c <path> Look for php.ini file in this directory
|
|
-d foo[=bar] Define INI entry foo with value 'bar'
|
|
-e Generate extended information for debugger/profiler
|
|
-z <file> Load Zend extension <file>.
|
|
-l Syntax check only (lint)
|
|
-m Show compiled in modules
|
|
-i PHP information
|
|
-h This help
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Here we list some of the most important command line options
|
|
with detailed explanations.
|
|
</para>
|
|
<para>
|
|
<table>
|
|
<title>Command line options</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>-q</entry>
|
|
<entry>
|
|
Suppress HTTP headers output. Normally PHP prints out
|
|
HTTP headers for the calling program (ie. webserver)
|
|
to hand on to the browser. When writing command line
|
|
applications these headers are useless.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-s</entry>
|
|
<entry>
|
|
Display the color highlighted source of the file
|
|
given with its name. This is the same as if you were
|
|
printing out the source using the
|
|
<function>highlight_file</function> function in
|
|
a PHP script.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-f</entry>
|
|
<entry>
|
|
Parse the file given, and search for syntactical and
|
|
fatal errors. This option implies -q. Use for
|
|
debugging purposes.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-v</entry>
|
|
<entry>
|
|
By calling PHP with this option, you can ask
|
|
it to print out its version number, ie: 4.0.6.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-C</entry>
|
|
<entry>
|
|
Normally PHP changes the working directory to the
|
|
running scripts directory. This makes it possible
|
|
for example, to open files in the same directory,
|
|
with only specifying the name of the file. If you
|
|
would like to disable this directory change, use
|
|
this option.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-c</entry>
|
|
<entry>
|
|
Using this option, you can specify an alternative
|
|
&php.ini; path, so PHP will
|
|
search your configurations file in this path
|
|
instead of the default one.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-d</entry>
|
|
<entry>
|
|
With this option, you can set individual
|
|
&php.ini; settings in the
|
|
time of running a script.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-l</entry>
|
|
<entry>
|
|
Check the file given for syntax errors. This
|
|
option implies -q. Use for debugging purposes.
|
|
This option won't find fatal errors (like undefined
|
|
functions). Use -f if you would like to test
|
|
for fatal errors too.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-m</entry>
|
|
<entry>
|
|
Using this option, PHP prints out the built in
|
|
(and loaded) PHP and Zend modules, the PHP
|
|
and Zend version numbers, and a short Zend
|
|
copyright notice.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-i</entry>
|
|
<entry>
|
|
This command line option calls
|
|
<function>phpinfo</function>, and prints
|
|
out the results. If PHP is not working well,
|
|
it is advisable to make a <literal>php -i</literal>
|
|
and see if any error messages are printed out
|
|
before or in place of the information tables.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-h</entry>
|
|
<entry>
|
|
With this option, you can get information about
|
|
the actual list of command line options and some
|
|
one line descriptions about what they do.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
-->
|
|
<para>
|
|
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 <literal>php.exe</literal> with the double click option of the
|
|
<literal>.php</literal> 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.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Script intended to be run from command line (script.php)</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
#!/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];
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
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: <varname>$argc</varname> and <varname>$argv</varname>. 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 (<varname>$argv[0]</varname>).
|
|
</para>
|
|
<para>
|
|
In the program above we checked if there are less or more than one
|
|
arguments. Also if the argument was <literal>--help</literal>,
|
|
<literal>-help</literal>, <literal>-h</literal> or <literal>-?</literal>,
|
|
we printed out the help message, printing the script name dynamically.
|
|
If we received some other argument we echoed that out.
|
|
</para>
|
|
<para>
|
|
If you would like to run the above script on Unix, you need to
|
|
make it executable, and simply call it as
|
|
<literal>script.php echothis</literal> or
|
|
<literal>script.php -h</literal>. On Windows, you can make a
|
|
batch file for this task:
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Batch file to run a command line PHP script (script.bat)</title>
|
|
<programlisting role="shell">
|
|
@c:\php\cli\php.exe script.php %1 %2 %3 %4
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
Assuming you named the above program
|
|
<filename>script.php</filename>, and you have your
|
|
CLI <filename>php.exe</filename> in
|
|
<filename>c:\php\cli\php.exe</filename> this batch file
|
|
will run it for you with your added options:
|
|
<literal>script.bat echothis</literal> or
|
|
<literal>script.bat -h</literal>.
|
|
</para>
|
|
<para>
|
|
See also the <link linkend="ref.readline">Readline</link>
|
|
extension documentation for more functions you can use
|
|
to enhance your command line applications in PHP.
|
|
</para>
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|