mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
1959 lines
58 KiB
XML
1959 lines
58 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>
|
|
The main focus of &cli.sapi;
|
|
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>
|
|
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 the 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 it is possible to 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>
|
|
Defaults to &false;, as it can be quite hard to read error messages
|
|
in the shell environment when they are cluttered up with uninterpreted
|
|
<acronym>HTML</acronym> tags.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
In a shell environment, it is usually desirable for output, such as
|
|
from <function>print</function>, <function>echo</function> and
|
|
friends, to be displayed immediately, and not held in a buffer.
|
|
Nonetheless, it is still possible to use
|
|
<link linkend="ref.outcontrol">output buffering</link> 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>
|
|
PHP in a shell environment tends to be used for a much more diverse
|
|
range of purposes than typical Web-based scripts, and as these can
|
|
be very long-running, the maximum execution time is set to unlimited.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.register-argc-argv">register_argc_argv</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
<para>
|
|
Setting this to &true; means that scripts executed via the
|
|
&cli; <acronym>SAPI</acronym> always have access to
|
|
<emphasis>argc</emphasis> (number of arguments passed to the
|
|
application) and <emphasis>argv</emphasis> (array of the actual
|
|
arguments).
|
|
</para>
|
|
<para>
|
|
The PHP variables <varname>$argc</varname>
|
|
and <varname>$argv</varname> are automatically set to the appropriate
|
|
values when using the &cli; <acronym>SAPI</acronym>. These values can
|
|
also be found in the <varname>$_SERVER</varname> array, for example:
|
|
<varname>$_SERVER['argv']</varname>.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.output-buffering">output_buffering</link></entry>
|
|
<entry>&false;</entry>
|
|
<entry>
|
|
<para>
|
|
Although 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; does 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
|
|
limitation is because the values are applied after all configuration
|
|
files have been parsed. However, their values can be changed
|
|
during runtime (although this is not sensible for all of them,
|
|
such as <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 information.
|
|
</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
|
|
at any time 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 <addr>:<port> Run with built-in web server.
|
|
-t <docroot> Specify document root <docroot> for built-in web server.
|
|
-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>.
|
|
--rz <name> Show information about Zend 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>
|
|
Run 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>
|
|
Specifies either a directory in which to look for
|
|
&php.ini;, or 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 this option is not specified, &php.ini; is searched for in the
|
|
<link linkend="configuration.file">default locations</link>.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-n</entry>
|
|
<entry>--no-php-ini</entry>
|
|
<entry>
|
|
<para>
|
|
Ignore &php.ini; completely.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-d</entry>
|
|
<entry>--define</entry>
|
|
<entry>
|
|
<para>
|
|
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>
|
|
Parse and execute the specified file. The
|
|
<option>-f</option> is optional and may be omitted - providing just
|
|
the filename to execute is sufficient.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-h and -?</entry>
|
|
<entry>--help and --usage</entry>
|
|
<entry>
|
|
Output a list of
|
|
command line options with one line descriptions of what they do.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-i</entry>
|
|
<entry>--info</entry>
|
|
<entry>
|
|
Calls <function>phpinfo</function>, and prints out the results.
|
|
If PHP is not working correctly, it is advisable to use the command
|
|
<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 very large.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-l</entry>
|
|
<entry>--syntax-check</entry>
|
|
<entry>
|
|
<para>
|
|
Provides a convenient way to perform only 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
|
|
the <option>-f</option> 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>
|
|
Allows execution of PHP included directly on 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 parse error if present.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Care must be taken when using this form of PHP not
|
|
to 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 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 using a shell other than sh/bash, further issues might be
|
|
experienced - if appropriate, a bug report should be opened at
|
|
<link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.
|
|
It is still easy to run into trouble when trying to use variables
|
|
(shell or PHP) in command-line code, or using backslashes for
|
|
escaping, so take great care when doing so. You have been warned!
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
<option>-r</option> is available in the &cli.sapi;, but not in the
|
|
<emphasis>CGI</emphasis> <acronym>SAPI</acronym>.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
This option is only intended for very basic code, so some
|
|
configuration directives (such as <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.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-R</entry>
|
|
<entry>--process-code</entry>
|
|
<entry>
|
|
<para>
|
|
PHP code to execute for every input line.
|
|
</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.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-E</entry>
|
|
<entry>--process-end</entry>
|
|
<entry>
|
|
<para>
|
|
PHP code to execute after processing the input.
|
|
</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>--server</entry>
|
|
<entry>
|
|
<para>
|
|
Starts <link linkend="features.commandline.webserver">built-in web
|
|
server</link>.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>-t</entry>
|
|
<entry>--docroot</entry>
|
|
<entry>
|
|
Specifies document root for <link
|
|
linkend="features.commandline.webserver">built-in web server</link>.
|
|
</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 writes
|
|
an HTML highlighted version of it to
|
|
standard output. Note that all it does is 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 comments and whitespace stripped.
|
|
</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 <filename>/etc/ld.so.conf</filename> on Linux systems, for
|
|
example). Passing a filename with an absolute path will
|
|
not use the system's library search path. A relative filename including
|
|
directory information will tell PHP to try
|
|
loading the extension relative to the current directory.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>--ini</entry>
|
|
<entry>
|
|
<para>
|
|
Show configuration file names and scanned directories.
|
|
<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>
|
|
Show information about the given function or class method (e.g.
|
|
number and name of the parameters).
|
|
</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).
|
|
</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).
|
|
</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>--rz</entry>
|
|
<entry>--rzendextension</entry>
|
|
<entry>
|
|
<para>
|
|
Show the configuration information for the given Zend extension (the
|
|
same information that is returned by <function>phpinfo</function>).
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>--ri</entry>
|
|
<entry>--rextinfo</entry>
|
|
<entry>
|
|
<para>
|
|
Show the configuration information for the given extension (the same
|
|
information that is returned by <function>phpinfo</function>).
|
|
The core configuration information
|
|
is 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[fcezi]</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>
|
|
There are three different ways of supplying the &cli.sapi; with PHP code
|
|
to be executed:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Tell 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>. Note that there is no
|
|
restriction on which files can be executed; in particular, the filename
|
|
is not required have a <literal>.php</literal> extension.
|
|
</para>
|
|
</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 with regard to shell variable substitution and
|
|
usage of quotes.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Read the example carefully: there are no beginning or ending tags! The
|
|
<option>-r</option> switch simply does not need them, and using them will
|
|
lead to a parse 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 create PHP code dynamically 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>
|
|
As with every shell application, the PHP binary accepts a number of
|
|
arguments; however, the PHP script can also receive further arguments. The
|
|
number of arguments that can be passed to your script is not limited by PHP
|
|
(and although the shell has a limit to the number of characters which can be
|
|
passed, this is not in general likely to be hit). The arguments passed to
|
|
the script are available in the global array <varname>$argv</varname>. The
|
|
first index (zero) always contains the name of the script as called from the
|
|
command line. Note that, if the code is executed in-line using the command
|
|
line switch <option>-r</option>, the value of <varname>$argv[0]</varname>
|
|
will be <literal>"Standard input code"</literal>; prior to PHP 7.2.0, it was a dash (<literal>"-"</literal>) instead. The same is true if the code is
|
|
executed via a pipe from <literal>STDIN</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
A second global variable, <varname>$argc</varname>,
|
|
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 to be passed to the script do not start with
|
|
the <literal>-</literal> character, there's nothing special to watch out for.
|
|
Passing an argument to the script which starts with a <literal>-</literal>
|
|
will cause trouble because the PHP interpreter thinks it has to handle it
|
|
itself, even before executing the script. To prevent this, use the argument
|
|
list separator <literal>--</literal>. After this separator has been parsed by
|
|
PHP, every following argument is passed untouched to the 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 the script and prevent PHP from showing its 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: make the first line of the script start with
|
|
<literal>#!/usr/bin/php</literal> (or whatever the path to your PHP &cli;
|
|
binary is if different). The rest of the file should contain normal PHP code
|
|
within the usual PHP starting and end tags. Once the execution attributes of
|
|
the file are set appropriately (e.g. <command>chmod +x test</command>),
|
|
the script can be executed like any other 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, it is now possible to 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 can be seen, in this case no special care needs to be taken when passing parameters
|
|
starting with <literal>-</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The PHP executable can be used to run PHP scripts absolutely independent of
|
|
the web server. On Unix systems, the special <literal>#!</literal> (or
|
|
"shebang") first line should be added to PHP scripts so that the system can
|
|
automatically tell which program should run the script. On Windows platforms,
|
|
it's possible to associate <filename>php.exe</filename> with the double
|
|
click option of the <literal>.php</literal> extension, or a batch file can
|
|
be created to run scripts through PHP. The special shebang first line for
|
|
Unix does no harm on Windows (as it's formatted as a PHP comment), so cross
|
|
platform programs can be written by including it. A simple example of
|
|
writing a command line PHP program is shown 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>
|
|
The script above includes the Unix shebang first line to indicate that this
|
|
file should be run by PHP. We are working with a &cli; version here, so
|
|
no <acronym>HTTP</acronym> headers will be output.
|
|
</para>
|
|
|
|
<para>
|
|
The program first checks that there is the required one argument (in
|
|
addition to the script name, which is also counted). If not, or if the
|
|
argument was <option>--help</option>, <option>-help</option>,
|
|
<option>-h</option> or <option>-?</option>, the help message is printed out,
|
|
using <varname>$argv[0]</varname> to dynamically print the script name as
|
|
typed on the command line. Otherwise, the argument is echoed out exactly as
|
|
received.
|
|
</para>
|
|
|
|
<para>
|
|
To run the above script on Unix, it must be made
|
|
executable, and called simply as <command>script.php echothis</command> or
|
|
<command>script.php -h</command>. On Windows, a batch file similar to the
|
|
following can be created 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 the above program is named <filename>script.php</filename>, and the
|
|
&cli; <filename>php.exe</filename> is in <filename>C:\php\php.exe</filename>,
|
|
this batch file will run it, passing on all appended 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 which can be used to enhance command line
|
|
applications in PHP.
|
|
</para>
|
|
|
|
<para>
|
|
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 described in <link linkend="install.windows.commandline">Command
|
|
Line PHP on Microsoft Windows</link>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
On Windows it is recommended to run PHP under an actual user account.
|
|
When running under a network service certain operations will fail, because
|
|
"No mapping between account names and security IDs was done".
|
|
</para>
|
|
</note>
|
|
</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 if reading the PHP script from
|
|
<literal>stdin</literal>.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Interactive shell: {{{-->
|
|
<section xml:id="features.commandline.interactive">
|
|
<title>Interactive shell</title>
|
|
|
|
<para>
|
|
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.
|
|
As of PHP 7.1.0 the interactive shell is also available on Windows, if the
|
|
<link linkend="book.readline">readline extension</link> is enabled.
|
|
</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>
|
|
Completion will also work for names that have been defined
|
|
during the current interactive shell session:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php > $fooThisIsAReallyLongVariableName = 42;
|
|
php > $foo[TAB]ThisIsAReallyLongVariableName
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
The interactive shell stores your history which can be accessed using the up
|
|
and down keys. The history is saved in the
|
|
<filename>~/.php_history</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
The &cli.sapi; provides
|
|
the &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>
|
|
It is also possible to set
|
|
&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>
|
|
|
|
<section xml:id="features.commandline.interactive.mode">
|
|
<title>Interactive mode</title>
|
|
<para>
|
|
If the readline extension is not available, prior to PHP 8.1.0, invoking the &cli.sapi; with the
|
|
<option>-a</option> option provided the interactive mode. In this mode, a
|
|
complete PHP script is supposed to be given via STDIN, and after termination
|
|
with <literal>CRTL+d</literal> (POSIX) or <literal>CTRL+z</literal>
|
|
followed by <literal>ENTER</literal> (Windows), this script is evaluated.
|
|
This is basically the same as invoking the &cli.sapi; without the <option>-a</option>
|
|
option.
|
|
</para>
|
|
<para>
|
|
As of PHP 8.1.0, invoking the &cli.sapi; with the <option>-a</option> option
|
|
fails, if the readline extension is not available.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Built-in CLI Web Server: {{{-->
|
|
<section xml:id="features.commandline.webserver">
|
|
<title>Built-in web server</title>
|
|
|
|
<warning>
|
|
<para>
|
|
This web server is designed to aid application development. It may also
|
|
be useful for testing purposes or for application demonstrations that are
|
|
run in controlled environments. It is not intended to be a full-featured
|
|
web server. It should not be used on a public network.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
The &cli.sapi; provides a built-in web server.
|
|
</para>
|
|
|
|
<para>
|
|
The web server runs only one single-threaded process, so
|
|
PHP applications will stall if a request is blocked.
|
|
</para>
|
|
|
|
<para>
|
|
URI requests are served from the current working directory where
|
|
PHP was started, unless the -t option is used to specify an
|
|
explicit document root. If a URI request does not specify a file,
|
|
then either index.php or index.html in the given directory are
|
|
returned. If neither file exists, the lookup for index.php and index.html
|
|
will be continued in the parent directory and so on until one is found or
|
|
the document root has been reached. If an index.php or index.html is found,
|
|
it is returned and $_SERVER['PATH_INFO'] is set to the trailing part of
|
|
the URI. Otherwise a 404 response code is returned.
|
|
</para>
|
|
|
|
<para>
|
|
If a PHP file is given on the command line when the web server is
|
|
started it is treated as a "router" script. The script is run at
|
|
the start of each HTTP request. If this script returns &false;,
|
|
then the requested resource is returned as-is. Otherwise the
|
|
script's output is returned to the browser.
|
|
</para>
|
|
|
|
<para>
|
|
Standard MIME types are returned for files with extensions: .3gp,
|
|
.apk, .avi, .bmp, .css, .csv, .doc, .docx, .flac, .gif, .gz,
|
|
.gzip, .htm, .html, .ics, .jpe, .jpeg, .jpg, .js, .kml, .kmz,
|
|
.m4a, .mov, .mp3, .mp4, .mpeg, .mpg, .odp, .ods, .odt, .oga, .ogg,
|
|
.ogv, .pdf, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text,
|
|
.tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, and .zip.
|
|
</para>
|
|
|
|
|
|
<table>
|
|
<title>Changelog: Supported MIME Types (file extensions)</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>5.5.12</entry>
|
|
<entry>
|
|
.xml, .xsl, and .xsd
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.5.7</entry>
|
|
<entry>
|
|
.3gp, .apk, .avi, .bmp, .csv, .doc, .docx, .flac, .gz, .gzip,
|
|
.ics, .kml, .kmz, .m4a, .mp3, .mp4, .mpg, .mpeg, .mov, .odp, .ods,
|
|
.odt, .oga, .pdf, .pptx, .pps, .qt, .swf, .tar, .text, .tif, .wav,
|
|
.wmv, .xls, .xlsx, and .zip
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.5.5</entry>
|
|
<entry>
|
|
.pdf
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.4.11</entry>
|
|
<entry>
|
|
.ogg, .ogv, and .webm
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.4.4</entry>
|
|
<entry>
|
|
.htm and .svg
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
|
|
<table>
|
|
<title>Changelog</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>7.4.0</entry>
|
|
<entry>
|
|
You can configure the built-in webserver to fork multiple workers
|
|
in order to test code that requires multiple concurrent requests to
|
|
the built-in webserver. Set the <envar>PHP_CLI_SERVER_WORKERS</envar>
|
|
environment variable to the number of desired workers before starting
|
|
the server.
|
|
This is not supported on Windows.
|
|
<warning>
|
|
<para>
|
|
This <emphasis>experimental</emphasis> feature is <emphasis>not</emphasis>
|
|
intended for production usage. Generally, the built-in Web Server is
|
|
<emphasis>not</emphasis> intended for production usage.
|
|
</para>
|
|
</warning>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
|
|
<example>
|
|
<title>Starting the web server</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ cd ~/public_html
|
|
$ php -S localhost:8000
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The terminal will show:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
|
|
Listening on localhost:8000
|
|
Document root is /home/me/public_html
|
|
Press Ctrl-C to quit
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
After URI requests for http://localhost:8000/ and
|
|
http://localhost:8000/myscript.html the terminal will show
|
|
something similar to:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
|
|
Listening on localhost:8000
|
|
Document root is /home/me/public_html
|
|
Press Ctrl-C to quit.
|
|
[Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
|
|
[Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
|
|
[Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
|
|
[Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
|
|
[Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Note that prior to PHP 7.4.0, symlinked statical resources have not been
|
|
accessible on Windows, unless the router script would handle these.
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Starting with a specific document root directory</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ cd ~/public_html
|
|
$ php -S localhost:8000 -t foo/
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The terminal will show:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
|
|
Listening on localhost:8000
|
|
Document root is /home/me/public_html/foo
|
|
Press Ctrl-C to quit
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Using a Router Script</title>
|
|
<para>
|
|
In this example, requests for images will display them, but requests for HTML files will display "Welcome to PHP":
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// router.php
|
|
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
|
|
return false; // serve the requested resource as-is.
|
|
} else {
|
|
echo "<p>Welcome to PHP</p>";
|
|
}
|
|
?>]]>
|
|
</programlisting>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php -S localhost:8000 router.php
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Checking for CLI Web Server Use</title>
|
|
<para>
|
|
To reuse a framework router script during development with the CLI web server and later also with a production web server:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// router.php
|
|
if (php_sapi_name() == 'cli-server') {
|
|
/* route static assets and return false */
|
|
}
|
|
/* go on with normal index.php operations */
|
|
?>]]>
|
|
</programlisting>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php -S localhost:8000 router.php
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Handling Unsupported File Types</title>
|
|
<para>
|
|
If you need to serve a static resource whose MIME type is not handled by the CLI web server, use:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// router.php
|
|
$path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
|
|
if ($path["extension"] == "el") {
|
|
header("Content-Type: text/x-script.elisp");
|
|
readfile($_SERVER["SCRIPT_FILENAME"]);
|
|
}
|
|
else {
|
|
return FALSE;
|
|
}
|
|
?>]]>
|
|
</programlisting>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php -S localhost:8000 router.php
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Accessing the CLI Web Server From Remote Machines</title>
|
|
<para>
|
|
You can make the web server accessible on port 8000 to any interface with:
|
|
</para>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
$ php -S 0.0.0.0:8000
|
|
]]>
|
|
</programlisting>
|
|
<warning>
|
|
<para>
|
|
The built-in Web Server should not be used on a public network.
|
|
</para>
|
|
</warning>
|
|
</example>
|
|
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<section xml:id="features.commandline.ini">
|
|
<title>INI settings</title>
|
|
<para>
|
|
<table>
|
|
<title>CLI SAPI Configuration Options</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>&Name;</entry>
|
|
<entry>&Default;</entry>
|
|
<entry>&Changeable;</entry>
|
|
<entry>&Changelog;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody xml:id="features.commandline.ini.list">
|
|
<row>
|
|
<entry><link linkend="ini.cli-server.color">cli_server.color</link></entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
<entry></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
|
|
&ini.descriptions.title;
|
|
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry xml:id="ini.cli-server.color">
|
|
<term>
|
|
<parameter>cli_server.color</parameter>
|
|
<type>bool</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enable the built-in development web server to use ANSI color coding
|
|
in terminal output.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</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
|
|
-->
|