mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
daf137f592
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@299622 c90b9560-bf6c-de11-be94-00142212c4b1
1589 lines
48 KiB
XML
1589 lines
48 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $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>
|
|
<titleabbrev>Command line usage</titleabbrev>
|
|
|
|
<!--Introduction: {{{-->
|
|
<section xml:id="features.commandline.introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
PHP supports a &cli.sapi; as of PHP 4.3.0. The main focus of this
|
|
<acronym>SAPI</acronym> is for developing shell applications with PHP. There
|
|
are quite a few differences between the &cli.sapi; and other
|
|
<acronym>SAPI</acronym>s which are explained in this chapter. It is worth
|
|
mentioning that &cli; and <acronym>CGI</acronym> are different
|
|
<acronym>SAPI</acronym>s although they do share many of the same behaviors.
|
|
</para>
|
|
|
|
<para>
|
|
The &cli.sapi; is enabled by default using
|
|
<option role="configure">--enable-cli</option>, but may be disabled using
|
|
the <option role="configure">--disable-cli</option> option when running
|
|
<command>./configure</command>.
|
|
</para>
|
|
|
|
<para>
|
|
The name, location and existence of the &cli;/<acronym>CGI</acronym>
|
|
binaries will differ depending on how PHP is installed on your system. By
|
|
default when executing <command>make</command>, both the <acronym>CGI</acronym>
|
|
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 <filename>php</filename>. What happens during
|
|
<command>make install</command> depends on your configure line. If a module
|
|
<acronym>SAPI</acronym> 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 <acronym>CGI</acronym> 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 <acronym>CGI</acronym> 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>
|
|
As of PHP 5, the &cli; binary is distributed in the main folder as <filename>
|
|
php.exe</filename> on Windows. The <acronym>CGI</acronym> version is
|
|
distributed as <filename>php-cgi.exe</filename>. Additionally, a <filename>
|
|
php-win.exe</filename> is distributed if PHP is configured using
|
|
<option role="configure">--enable-cli-win32</option>. This does the same as
|
|
the &cli; version, except that it doesn't output anything and thus provides
|
|
no console.
|
|
</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 <acronym>CGI</acronym> 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 is available by typing <command>man
|
|
php</command> in your shell environment.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Differences: {{{-->
|
|
<section xml:id="features.commandline.differences">
|
|
<title>Differences to other <acronym>SAPI</acronym>s</title>
|
|
|
|
<para>
|
|
Remarkable differences of the &cli; <acronym>SAPI</acronym> compared to other
|
|
<acronym>SAPI</acronym>s:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Unlike the <acronym>CGI</acronym> <acronym>SAPI</acronym>, no headers are
|
|
written to the output.
|
|
</para>
|
|
<para>
|
|
Though the <acronym>CGI</acronym> <acronym>SAPI</acronym> provides a way
|
|
to suppress HTTP headers, there's no equivalent switch to enable them in
|
|
the &cli.sapi;.
|
|
</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 <acronym>CGI</acronym> 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 <acronym>HTML</acronym> formatting).
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
There are certain &php.ini; directives which are overridden by the
|
|
&cli.sapi; 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>&cli; <acronym>SAPI</acronym> 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 <acronym>HTML</acronym>
|
|
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 &cli; <acronym>SAPI</acronym>.
|
|
</para>
|
|
<para>
|
|
The PHP variables <varname>$argc</varname>
|
|
and <varname>$argv</varname> are registered and filled in with the appropriate
|
|
values when using the &cli; <acronym>SAPI</acronym>. You can also go
|
|
through <varname>$_SERVER</varname> or. Example:
|
|
<varname>$_SERVER['argv']</varname>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.output-buffering">output_buffering</link></entry>
|
|
<entry>&false;</entry>
|
|
<entry>
|
|
<para>
|
|
Altough the &php.ini; setting is hardcoded to &false; the
|
|
<link linkend="book.outcontrol">Output buffering</link> functions
|
|
are available.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.max-input-time">max_input_time</link></entry>
|
|
<entry>&false;</entry>
|
|
<entry>
|
|
<para>
|
|
The PHP &cli; doesn't not support GET, POST or file uploads.
|
|
</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>
|
|
<note>
|
|
<para>
|
|
It is recommended to set
|
|
<link linkend="ini.ignore-user-abort">ignore_user_abort</link> for
|
|
command line scripts. See <function>ignore_user_abort</function> for
|
|
more info.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
To ease working in the shell environment, a number of constants are
|
|
defined for <link linkend="features.commandline.io-streams">I/O streams
|
|
</link>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The &cli.sapi; does <emphasis role="strong">not</emphasis> change the
|
|
current directory to the directory of the executed script!
|
|
</para>
|
|
<example>
|
|
<title>
|
|
Example showing the difference to the <acronym>CGI</acronym>
|
|
<acronym>SAPI</acronym>:
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Our simple test application named test.php
|
|
echo getcwd(), "\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
When using the <acronym>CGI</acronym> 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 &cli.sapi; 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>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
The <acronym>CGI</acronym> <acronym>SAPI</acronym> supports this
|
|
&cli.sapi; behaviour by means of the <option>-C</option> switch when run
|
|
from the command line.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Options: {{{-->
|
|
<section xml:id="features.commandline.options">
|
|
<title>Command line options</title>
|
|
<titleabbrev>Options</titleabbrev>
|
|
|
|
<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 Output HTML syntax highlighted source.
|
|
-v Version number
|
|
-w Output 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>
|
|
<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. For more information, see the <link
|
|
linkend="features.commandline.interactive">Interactive shell</link>
|
|
section.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-b</entry>
|
|
<entry>--bindpath</entry>
|
|
<entry>
|
|
<para>
|
|
Bind Path for external FASTCGI Server mode (<acronym>CGI</acronym>
|
|
only).
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-C</entry>
|
|
<entry>--no-chdir</entry>
|
|
<entry>
|
|
<para>
|
|
Do not chdir to the script's directory (<acronym>CGI</acronym> only).
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-q</entry>
|
|
<entry>--no-header</entry>
|
|
<entry>
|
|
<para>
|
|
Quiet-mode. Suppress <acronym>HTTP</acronym> header output
|
|
(<acronym>CGI</acronym> only).
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-T</entry>
|
|
<entry>--timing</entry>
|
|
<entry>
|
|
<para>
|
|
Measure execution time of script repeated <varname>count</varname>
|
|
times (<acronym>CGI</acronym> only).
|
|
</para>
|
|
</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.
|
|
</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><example>
|
|
<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>
|
|
</example></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 <acronym>CGI</acronym> 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><example>
|
|
<title>Printing built in (and loaded) PHP and Zend modules</title>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -m
|
|
[PHP Modules]
|
|
xml
|
|
tokenizer
|
|
standard
|
|
session
|
|
posix
|
|
pcre
|
|
overload
|
|
mysql
|
|
mbstring
|
|
ctype
|
|
|
|
[Zend Modules]
|
|
]]>
|
|
</screen>
|
|
</example></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>
|
|
<example>
|
|
<title>Getting a syntax error when using double quotes</title>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -r "$foo = get_defined_constants();"
|
|
PHP Parse error: syntax error, unexpected '=' in Command line code on line 1
|
|
|
|
Parse error: syntax error, unexpected '=' in Command line code on line 1
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<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>
|
|
</informalexample>
|
|
|
|
<para>
|
|
The correct way would be to use single quotes <literal>'</literal>.
|
|
Variables in single-quoted strings are not expanded
|
|
by sh/bash.
|
|
</para>
|
|
<example>
|
|
<title>Using single quotes to prevent the shell's variable
|
|
substitution</title>
|
|
<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>
|
|
</example>
|
|
<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 &cli.sapi; and not in the
|
|
<emphasis>CGI</emphasis> <acronym>SAPI</acronym>.
|
|
</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><example>
|
|
<title>Using <option>-v</option> to get the <acronym>SAPI</acronym>
|
|
name and the version of PHP and Zend</title>
|
|
<screen>
|
|
<![CDATA[
|
|
$ php -v
|
|
PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
|
|
Copyright (c) 1997-2009 The PHP Group
|
|
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
|
|
]]>
|
|
</screen>
|
|
</example></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="book.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="book.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="book.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 => 2009.20
|
|
Timezone Database => internal
|
|
Default timezone => Europe/Oslo
|
|
|
|
Directive => Local Value => Master Value
|
|
date.timezone => Europe/Oslo => Europe/Oslo
|
|
date.default_latitude => 59.930972 => 59.930972
|
|
date.default_longitude => 10.776699 => 10.776699
|
|
date.sunset_zenith => 90.583333 => 90.583333
|
|
date.sunrise_zenith => 90.583333 => 90.583333
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Options <literal>-rBRFEH</literal>, <literal>--ini</literal> and
|
|
<literal>--r[fcei]</literal> are available only in &cli;.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Usage: {{{-->
|
|
<section xml:id="features.commandline.usage">
|
|
<title>Executing PHP files</title>
|
|
<titleabbrev>Usage</titleabbrev>
|
|
|
|
<para>
|
|
The &cli.sapi; 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, and 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 codeis 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 on Unix systems, 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> (substitute with the path to your PHP &cli;
|
|
binary if necessary. 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>
|
|
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 <acronym>HTTP</acronym> 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>
|
|
|
|
<para>
|
|
If you are on Windows, PHP can be configured to run without the need to
|
|
supply the <filename>C:\php\php.exe</filename> or the <literal>.php</literal>
|
|
extension, as descibed in <link linkend="install.windows.commandline">Command
|
|
Line PHP on Microsoft Windows</link>.
|
|
</para>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--I/O Streams: {{{-->
|
|
<section xml:id="features.commandline.io-streams">
|
|
<title>Input/output streams</title>
|
|
<titleabbrev>I/O streams</titleabbrev>
|
|
|
|
<para>
|
|
The &cli.sapi; defines a few constants for I/O streams to make programming
|
|
for the command line a bit easier.
|
|
</para>
|
|
|
|
<para>
|
|
<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>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Interactive shell: {{{-->
|
|
<section xml:id="features.commandline.interactive">
|
|
<title>Interactive shell</title>
|
|
|
|
<para>
|
|
As of PHP 5.1.0, the &cli.sapi; provides an interactive shell using the
|
|
<option>-a</option> option if PHP is compiled with the <option
|
|
role="configure">--with-readline</option> option.
|
|
</para>
|
|
|
|
<para>
|
|
Using the interactive shell you are able to type PHP code and have it
|
|
executed directly.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Executing code using the interactive shell</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php -a
|
|
Interactive shell
|
|
|
|
php > echo 5+8;
|
|
13
|
|
php > function addTwo($n)
|
|
php > {
|
|
php { return $n + 2;
|
|
php { }
|
|
php > var_dump(addtwo(2));
|
|
int(4)
|
|
php >
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
The interactive shell also features tab completion for functions,
|
|
constants, class names, variables, static method calls and class
|
|
constants.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Tab completion</title>
|
|
<simpara>
|
|
Pressing the tab key twice when there are multiple possible completions
|
|
will result in a list of these completions:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > strp[TAB][TAB]
|
|
strpbrk strpos strptime
|
|
php > strp
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
When there is only one possible completion, pressing tab once will
|
|
complete the rest on the same line:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > strpt[TAB]ime(
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
It is also possible doing completion on things that have been defined
|
|
during the interactive shell session:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > $fooThisIsAReallyLongVariableName = 42;
|
|
php > $foo[TAB]ThisIsAReallyLongVariableName
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
The interactive shell stores your history and can be accessed using the up
|
|
and down keys. The history is saved in the
|
|
<filename>~/.php_history</filename> file.
|
|
</para>
|
|
|
|
<!-- NOT YET AVAILABLE, UNCOMMENT AND FIX VERSIONS WHEN RELEASED
|
|
<para>
|
|
As of [whatever becomes the next version], the &cli.sapi; provides
|
|
two new &php.ini; settings: <parameter>cli.pager</parameter> and
|
|
<parameter>cli.prompt</parameter>. The <parameter>cli.pager</parameter>
|
|
setting allows an external program (such as <filename>less</filename>) to
|
|
act as a pager for the output instead of being displayed directly on the
|
|
screen. The <parameter>cli.prompt</parameter> setting makes it possible to
|
|
change the <literal>php ></literal> prompt.
|
|
</para>
|
|
|
|
<para>
|
|
In [whatever becoems the next version] it was also made possible setting
|
|
&php.ini; settings in the interactive shell using a shorthand notation.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Setting &php.ini; settings in the interactive shell</title>
|
|
<simpara>
|
|
The <parameter>cli.prompt</parameter> setting:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > #cli.prompt=hello world :>
|
|
hello world :>
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
Using backticks it is possible to have PHP code executed in the prompt:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > #cli.prompt=`echo date('H:i:s');` php >
|
|
15:49:35 php > echo 'hi';
|
|
hi
|
|
15:49:43 php > sleep(2);
|
|
15:49:45 php >
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
Setting the pager to <filename>less</filename>:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > #cli.pager=less
|
|
php > phpinfo();
|
|
(output displayed in less)
|
|
php >
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
The <parameter>cli.prompt</parameter> setting supports a few escape
|
|
sequences:
|
|
<table>
|
|
<title><parameter>cli.prompt</parameter> escape sequences</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Sequence:</entry>
|
|
<entry>Description:</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>\e</literal></entry>
|
|
<entry>
|
|
Used for adding colors to the prompt. An example could be
|
|
<literal>\e[032m\v \e[031m\b \e[34m\> \e[0m</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>\v</literal></entry>
|
|
<entry>The PHP version.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>\b</literal></entry>
|
|
<entry>
|
|
Indicates which block PHP is in. For instance <literal>/*</literal> to
|
|
indicate being inside a multi-line comment. The outer scope is denoted by
|
|
<literal>php</literal>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>\></literal></entry>
|
|
<entry>
|
|
Indicates the prompt character. By default this is
|
|
<literal>></literal>, but changes when the shell is inside an
|
|
unterminated block or string. Possible characters are: <literal>' " {
|
|
( ></literal>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</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>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
</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:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=marker fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|