mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
76a256e435
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@283795 c90b9560-bf6c-de11-be94-00142212c4b1
1293 lines
40 KiB
XML
1293 lines
40 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<chapter xml:id="features.commandline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Using PHP from the command line</title>
|
|
<para>
|
|
As of version 4.3.0, PHP supports a new
|
|
<literal>SAPI</literal> type (<literal>Server Application Programming Interface</literal>)
|
|
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
|
|
PHP. 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
|
|
PHP 4.2.0, but was still experimental and had
|
|
to be explicitly enabled with <option role="configure">--enable-cli</option> when running
|
|
<command>./configure</command>. Since PHP 4.3.0 the
|
|
<literal>CLI SAPI</literal> is no longer experimental and the option
|
|
<option role="configure">--enable-cli</option> is on by default. You may use
|
|
<option role="configure">--disable-cli</option> 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 <command>make</command>, both the CGI and CLI are built and
|
|
placed as <filename>sapi/cgi/php-cgi</filename> and <filename>sapi/cli/php</filename>
|
|
respectively, in your PHP source directory. You will note that both are
|
|
named php. What happens during <command>make install</command> depends on
|
|
your configure line. If a module SAPI is chosen during configure, such as apxs, or the
|
|
<option role="configure">--disable-cgi</option> option is used, the CLI is copied to
|
|
<filename>{PREFIX}/bin/php</filename> during <command>make install</command>
|
|
otherwise the CGI is placed there. So, for example, if <option role="configure">--with--apxs
|
|
</option> is in your configure line then the CLI is copied to
|
|
<filename>{PREFIX}/bin/php</filename> during <command>make
|
|
install</command>. If you want to override the installation of the CGI
|
|
binary, use <command>make install-cli</command> after <command>make
|
|
install</command>. Alternatively you can specify <option role="configure">
|
|
--disable-cgi</option> in your configure line.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Because both <option role="configure">--enable-cli</option> and
|
|
<option role="configure">--enable-cgi</option> are enabled by default,
|
|
simply having <option role="configure">--enable-cli</option> in your
|
|
configure line does not necessarily mean the CLI will be copied as
|
|
<filename>{PREFIX}/bin/php</filename> during <command>make install</command>.
|
|
</para>
|
|
</note>
|
|
<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 <filename class="directory">cli</filename>, so <filename>cli/php.exe
|
|
</filename>. Starting with PHP 5, the CLI is distributed in the main folder,
|
|
named <filename>php.exe</filename>. The CGI version is distributed as
|
|
<filename>php-cgi.exe</filename>.
|
|
</para>
|
|
<para>
|
|
As of PHP 5, a new <filename>php-win.exe</filename> 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
|
|
<option role="configure">--enable-cli-win32</option>.
|
|
</para>
|
|
<note>
|
|
<title>What SAPI do I have?</title>
|
|
<para>
|
|
From a shell, typing <command>php -v</command> will tell you
|
|
whether <filename>php</filename> is CGI or CLI. See also the function
|
|
<function>php_sapi_name</function> and the constant <constant>
|
|
PHP_SAPI</constant>.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
A Unix <literal>man</literal>ual page was added in PHP 4.3.2. You may
|
|
view this by typing <command>man php</command> in your shell environment.
|
|
</para>
|
|
</note>
|
|
<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 <option>-q</option>
|
|
and <option>--no-header</option> 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.
|
|
(<option>-C</option> and <option>--no-chdir</option> 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 HTML
|
|
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 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.
|
|
</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 PHP 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
|
|
<varname>$_SERVER</varname> 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>
|
|
<para>An already opened stream to <literal>stdin</literal>. This saves
|
|
opening it with
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$stdin = fopen('php://stdin', 'r');
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
If you want to read single line from <literal>stdin</literal>, you can
|
|
use
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$line = trim(fgets(STDIN)); // reads one line from STDIN
|
|
fscanf(STDIN, "%d\n", $number); // reads number from STDIN
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>STDOUT</constant></entry>
|
|
<entry><para>
|
|
An already opened stream to <literal>stdout</literal>. This saves
|
|
opening it with
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$stdout = fopen('php://stdout', 'w');
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>STDERR</constant></entry>
|
|
<entry>
|
|
<para>
|
|
An already opened stream to <literal>stderr</literal>.
|
|
This saves opening it with
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$stderr = fopen('php://stderr', 'w');
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
</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="shell">
|
|
<![CDATA[
|
|
php -r 'fwrite(STDERR, "stderr\n");'
|
|
]]>
|
|
</programlisting>
|
|
You do not need to explicitly close these streams, as they are closed
|
|
automatically by PHP when your script ends.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
These constants are not available in case of reading PHP script from
|
|
<literal>stdin</literal>.
|
|
</para>
|
|
</note>
|
|
</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>
|
|
<informalexample>
|
|
<para>
|
|
Example showing the difference to the <literal>CGI SAPI</literal>:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Our simple test application named test.php
|
|
echo getcwd(), "\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
When using the <literal>CGI</literal> version, the output is:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
$ pwd
|
|
/tmp
|
|
|
|
$ php -q another_directory/test.php
|
|
/tmp/another_directory
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
This clearly shows that PHP changes its current
|
|
directory to the one of the executed script.
|
|
</para>
|
|
<para>
|
|
Using the <literal>CLI SAPI</literal> yields:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
$ pwd
|
|
/tmp
|
|
|
|
$ php -f another_directory/test.php
|
|
/tmp
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
This allows greater flexibility when writing shell tools in PHP.
|
|
</para>
|
|
</informalexample>
|
|
<note>
|
|
<para>
|
|
The <literal>CGI SAPI</literal> supports this <literal>CLI SAPI</literal>
|
|
behaviour by means of the <option>-C</option> switch when run from the
|
|
command line.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The list of command line options provided by the PHP
|
|
binary can be queried anytime by running PHP with the
|
|
<option>-h</option> switch:
|
|
<screen>
|
|
<![CDATA[
|
|
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>.
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The <literal>CLI SAPI</literal> has three different ways of getting the
|
|
PHP code you want to execute:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Telling PHP to execute a certain file.
|
|
</para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
php my_script.php
|
|
|
|
php -f my_script.php
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
<para>
|
|
Both ways (whether using the <option>-f</option> switch or not) execute
|
|
the file <filename>my_script.php</filename>. You can choose any file to
|
|
execute - your PHP scripts do not have to end with the
|
|
<literal>.php</literal> extension but can have any name or extension
|
|
you wish.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If you need to pass arguments to your scripts you need to pass
|
|
<literal>--</literal> as the first argument when using the
|
|
<option>-f</option> switch.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Pass the PHP code to execute directly on the command
|
|
line.
|
|
</para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
php -r 'print_r(get_defined_constants());'
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
<para>
|
|
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
|
|
<option>-r</option> switch simply does not need them. Using them will
|
|
lead to a parser error.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Provide the PHP code to execute via standard input
|
|
(<literal>stdin</literal>).
|
|
</para>
|
|
<para>
|
|
This gives the powerful ability to dynamically create
|
|
PHP code and feed it to the binary, as shown in this
|
|
(fictional) example:
|
|
</para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
$ some_application | some_filter | php | sort -u >final_output.txt
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</listitem>
|
|
</orderedlist>
|
|
You cannot combine any of the three ways to execute code.
|
|
</para>
|
|
<para>
|
|
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 <varname>$argv</varname>. The zero index always contains the script
|
|
name (which is <literal>-</literal> in case the PHP code
|
|
is coming from either standard input or from the command line switch
|
|
<option>-r</option>). The second registered global variable is
|
|
<varname>$argc</varname> which contains the number of elements in the
|
|
<varname>$argv</varname> 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 PHP
|
|
itself thinks it has to handle it. To prevent this, use the argument list
|
|
separator <literal>--</literal>. After this separator has been parsed by
|
|
PHP, every argument following it is passed
|
|
untouched to your script.
|
|
</para>
|
|
<informalexample>
|
|
<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>
|
|
</informalexample>
|
|
<para>
|
|
However, there's another way of using PHP 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 PHP code included within the PHP
|
|
starting and end tags. Once you have set the execution attributes of the file
|
|
appropriately (e.g. <command>chmod +x test</command>) your script can be
|
|
executed like a normal shell or perl script:
|
|
</para>
|
|
<example>
|
|
<title>Execute PHP script as shell script</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
#!/usr/bin/php
|
|
<?php
|
|
var_dump($argv);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Assuming this file is named <filename>test</filename> in the current
|
|
directory, we can now do the following:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
$ chmod +x test
|
|
$ ./test -h -- foo
|
|
array(4) {
|
|
[0]=>
|
|
string(6) "./test"
|
|
[1]=>
|
|
string(2) "-h"
|
|
[2]=>
|
|
string(2) "--"
|
|
[3]=>
|
|
string(3) "foo"
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<para>
|
|
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>-a</entry>
|
|
<entry>--interactive</entry>
|
|
<entry>
|
|
<para>
|
|
Runs PHP interactively. If you compile PHP with the <link
|
|
linkend="ref.readline">Readline</link> 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
|
|
<filename>~/.php_history</filename> file.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Files included through <link
|
|
linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
|
|
linkend="ini.auto-append-file">auto_append_file</link> are parsed in
|
|
this mode but with some restrictions - e.g. functions have to be
|
|
defined before called.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
<link linkend="language.oop5.autoload">Autoloading</link> is not available if using PHP in CLI
|
|
interactive mode.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-c</entry>
|
|
<entry>--php-ini</entry>
|
|
<entry>
|
|
<para>
|
|
This option can either specify a directory where to look for
|
|
&php.ini; or specify a custom <literal>INI</literal> file
|
|
(which does not need to be named &php.ini;), e.g.:
|
|
</para>
|
|
<para><informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -c /custom/directory/ my_script.php
|
|
|
|
$ php -c /custom/directory/custom-file.ini my_script.php
|
|
]]>
|
|
</screen>
|
|
</informalexample></para>
|
|
<para>
|
|
If you don't specify this option, file is searched in
|
|
<link linkend="configuration.file">default locations</link>.
|
|
</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><informalexample>
|
|
<para>
|
|
Examples (lines are wrapped for layout reasons):
|
|
</para>
|
|
<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>
|
|
</informalexample></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-e</entry>
|
|
<entry>--profile-info</entry>
|
|
<entry>
|
|
<para>
|
|
Activate the extended information mode, to be used by a
|
|
debugger/profiler.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-f</entry>
|
|
<entry>--file</entry>
|
|
<entry>
|
|
<para>
|
|
Parses and executes the given filename to the <option>-f</option>
|
|
option. This switch is optional and can be left out. Only providing
|
|
the filename to execute is sufficient.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
To pass arguments to scripts the first argument needs to be
|
|
<literal>--</literal>, otherwise PHP will interperate them as PHP
|
|
options.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-h and -?</entry>
|
|
<entry>--help and --usage</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>-i</entry>
|
|
<entry>--info</entry>
|
|
<entry>
|
|
This command line option calls <function>phpinfo</function>, and prints
|
|
out the results. If PHP is not working correctly, it is
|
|
advisable to use <command>php -i</command> 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 <acronym>HTML</acronym>
|
|
and therefore quite huge.
|
|
</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 PHP 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>-1</literal>.
|
|
</para>
|
|
<para>
|
|
This option won't find fatal errors (like undefined functions). Use
|
|
<option>-f</option> if you would like to test for fatal errors too.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This option does not work together with the <option>-r</option>
|
|
option.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-m</entry>
|
|
<entry>--modules</entry>
|
|
<entry>
|
|
<para><informalexample>
|
|
<para>
|
|
Using this option, PHP prints out the built in (and loaded) PHP and
|
|
Zend modules:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -m
|
|
[PHP Modules]
|
|
xml
|
|
tokenizer
|
|
standard
|
|
session
|
|
posix
|
|
pcre
|
|
overload
|
|
mysql
|
|
mbstring
|
|
ctype
|
|
|
|
[Zend Modules]
|
|
]]>
|
|
</screen>
|
|
</informalexample></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-r</entry>
|
|
<entry>--run</entry>
|
|
<entry>
|
|
<para>
|
|
This option allows execution of PHP right from
|
|
within the command line. The PHP 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 PHP
|
|
to not collide with command line variable substitution done by the
|
|
shell.
|
|
</para>
|
|
<informalexample>
|
|
<para>
|
|
Example showing a parser error
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -r "$foo = get_defined_constants();"
|
|
Command line code(1) : Parse error - parse error, unexpected '='
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
<para>
|
|
The problem here is that the sh/bash performs variable substitution
|
|
even when using double quotes <literal>"</literal>. Since the
|
|
variable <varname>$foo</varname> is unlikely to be defined, it
|
|
expands to nothing which results in the code passed to
|
|
PHP for execution actually reading:
|
|
</para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -r " = get_defined_constants();"
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
The correct way would be to use single quotes <literal>'</literal>.
|
|
Variables in single-quoted strings are not expanded
|
|
by sh/bash.
|
|
</para>
|
|
<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>
|
|
</informalexample>
|
|
<para>
|
|
If you are using a shell different from sh/bash, you might experience
|
|
further issues. Feel free to open a bug report at
|
|
<link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.
|
|
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>
|
|
<option>-r</option> is available in the <emphasis>CLI</emphasis>
|
|
SAPI and not in the <emphasis>CGI</emphasis> SAPI.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
This option is meant for a very basic stuff. Thus some configuration
|
|
directives (e.g. <link
|
|
linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
|
|
linkend="ini.auto-append-file">auto_append_file</link>) are ignored
|
|
in this mode.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-B</entry>
|
|
<entry>--process-begin</entry>
|
|
<entry>
|
|
<para>
|
|
PHP code to execute before processing stdin. Added in PHP 5.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-R</entry>
|
|
<entry>--process-code</entry>
|
|
<entry>
|
|
<para>
|
|
PHP code to execute for every input line. Added in PHP 5.
|
|
</para>
|
|
<para>
|
|
There are two special variables available in this mode:
|
|
<varname>$argn</varname> and <varname>$argi</varname>.
|
|
<varname>$argn</varname> will contain the line PHP is processing at
|
|
that moment, while <varname>$argi</varname> will contain the line
|
|
number.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-F</entry>
|
|
<entry>--process-file</entry>
|
|
<entry>
|
|
<para>
|
|
PHP file to execute for every input line. Added in PHP 5.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-E</entry>
|
|
<entry>--process-end</entry>
|
|
<entry>
|
|
<para>
|
|
PHP code to execute after processing the input. Added in PHP 5.
|
|
</para>
|
|
<para><example>
|
|
<title>Using the <option>-B</option>, <option>-R</option> and
|
|
<option>-E</option> options to count the number of lines of a
|
|
project.
|
|
</title>
|
|
<screen>
|
|
<![CDATA[
|
|
$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
|
|
Total Lines: 37328
|
|
]]>
|
|
</screen>
|
|
</example></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-s</entry>
|
|
<entry>--syntax-highlight and --syntax-highlighting</entry>
|
|
<entry>
|
|
<para>
|
|
Display colour syntax highlighted source.
|
|
</para>
|
|
<para>
|
|
This option uses the internal mechanism to parse the file and produces
|
|
a HTML 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>
|
|
HTML tags, no HTML headers.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This option does not work together with the <option>-r</option>
|
|
option.
|
|
</para>
|
|
</note>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-v</entry>
|
|
<entry>--version</entry>
|
|
<entry>
|
|
<para><informalexample>
|
|
<para>
|
|
Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
|
|
</para>
|
|
<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>
|
|
</informalexample></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 <option>-r</option>
|
|
option.
|
|
</para>
|
|
</note>
|
|
</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 PHP only to try to
|
|
load the extension relative to the current directory.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>--ini</entry>
|
|
<entry>
|
|
<para>
|
|
Shows configuration file names and scanned directories. Available as
|
|
of PHP 5.2.3.
|
|
<example>
|
|
<title><literal>--ini</literal> example</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php --ini
|
|
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
|
|
Loaded Configuration File: /usr/dev/php/5.2/lib/php.ini
|
|
Scan for additional .ini files in: (none)
|
|
Additional .ini files parsed: (none)
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>--rf</entry>
|
|
<entry>--rfunction</entry>
|
|
<entry>
|
|
<para>
|
|
Shows information about the given function or class method (e.g.
|
|
number and name of the parameters). Available as of PHP 5.1.2.
|
|
</para>
|
|
<para>
|
|
This option is only available if PHP was compiled with
|
|
<link linkend="language.oop5.reflection">Reflection</link> support.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>basic <literal>--rf</literal> usage</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php --rf var_dump
|
|
Function [ <internal> public function var_dump ] {
|
|
|
|
- Parameters [2] {
|
|
Parameter #0 [ <required> $var ]
|
|
Parameter #1 [ <optional> $... ]
|
|
}
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>--rc</entry>
|
|
<entry>--rclass</entry>
|
|
<entry>
|
|
<para>
|
|
Show information about the given class (list of constants, properties
|
|
and methods). Available as of PHP 5.1.2.
|
|
</para>
|
|
<para>
|
|
This option is only available if PHP was compiled with
|
|
<link linkend="language.oop5.reflection">Reflection</link> support.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><literal>--rc</literal> example</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php --rc Directory
|
|
Class [ <internal:standard> class Directory ] {
|
|
|
|
- Constants [0] {
|
|
}
|
|
|
|
- Static properties [0] {
|
|
}
|
|
|
|
- Static methods [0] {
|
|
}
|
|
|
|
- Properties [0] {
|
|
}
|
|
|
|
- Methods [3] {
|
|
Method [ <internal> public method close ] {
|
|
}
|
|
|
|
Method [ <internal> public method rewind ] {
|
|
}
|
|
|
|
Method [ <internal> public method read ] {
|
|
}
|
|
}
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>--re</entry>
|
|
<entry>--rextension</entry>
|
|
<entry>
|
|
<para>
|
|
Show information about the given extension (list of &php.ini; options,
|
|
defined functions, constants and classes). Available as of PHP 5.1.2.
|
|
</para>
|
|
<para>
|
|
This option is only available if PHP was compiled with
|
|
<link linkend="language.oop5.reflection">Reflection</link> support.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><literal>--re</literal> example</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php --re json
|
|
Extension [ <persistent> extension #19 json version 1.2.1 ] {
|
|
|
|
- Functions {
|
|
Function [ <internal> function json_encode ] {
|
|
}
|
|
Function [ <internal> function json_decode ] {
|
|
}
|
|
}
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>--ri</entry>
|
|
<entry>--rextinfo</entry>
|
|
<entry>
|
|
<para>
|
|
Shows the configuration information for the given extension (the same
|
|
information that is returned by <function>phpinfo</function>).
|
|
Available as of PHP 5.2.2. The core configuration information
|
|
are available using "main" as extension name.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><literal>--ri</literal> example</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php --ri date
|
|
|
|
date
|
|
|
|
date/time support => enabled
|
|
"Olson" Timezone Database Version => 2007.5
|
|
Timezone Database => internal
|
|
Default timezone => Europe/Oslo
|
|
|
|
Directive => Local Value => Master Value
|
|
date.timezone => Europe/Oslo => Europe/Oslo
|
|
date.default_latitude => 59.22482 => 59.22482
|
|
date.default_longitude => 11.018084 => 11.018084
|
|
date.sunset_zenith => 90.583333 => 90.583333
|
|
date.sunrise_zenith => 90.583333 => 90.583333
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</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 <filename>php.exe</filename> 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 <option>--help</option>,
|
|
<option>-help</option>, <option>-h</option> or <option>-?</option>,
|
|
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
|
|
<command>script.php echothis</command> or
|
|
<command>script.php -h</command>. 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">
|
|
<![CDATA[
|
|
@echo OFF
|
|
"C:\php\php.exe" script.php %*
|
|
]]>
|
|
</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\php.exe</filename> this batch file
|
|
will run it for you with your added options:
|
|
<command>script.bat echothis</command> or
|
|
<command>script.bat -h</command>.
|
|
</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
|
|
-->
|