mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
0b5dd8ab64
The PHP_CLI_SERVER_WORKERS feature, which enables the built-in web server to fork multiple workers for handling concurrent requests, is not documented. I'm only including this in the changelog for the commandline features page and not the migration guide as per previous discussions. The feature was intended for running opcache tests in QA and shouldn't be advertised. However, documenting its existence is still necessary. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@349267 c90b9560-bf6c-de11-be94-00142212c4b1
1940 lines
57 KiB
XML
1940 lines
57 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>
|
|
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 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 enviroment 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>
|
|
<note>
|
|
<para>
|
|
To pass arguments to a script, the first argument must be
|
|
<literal>--</literal>, otherwise PHP will interpret them as PHP
|
|
options.
|
|
</para>
|
|
</note>
|
|
</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 commnad-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. 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>--server</entry>
|
|
<entry>
|
|
<para>
|
|
Starts <link linkend="features.commandline.webserver">built-in web
|
|
server</link>. Available as of PHP 5.4.0.
|
|
</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>.
|
|
Available as of PHP 5.4.0.
|
|
</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. 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>
|
|
Show 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>--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>).
|
|
Available as of PHP 5.4.0.
|
|
</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>).
|
|
Available as of PHP 5.2.2. 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>
|
|
<note>
|
|
<para>
|
|
If arguments need to be passed to the script when using
|
|
<option>-f</option>, the first argument must be <literal>--</literal>.
|
|
</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 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 just a dash (<literal>-</literal>). 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.legacy.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 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>
|
|
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.
|
|
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>
|
|
As of PHP 5.4.0, 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>
|
|
In PHP 5.4.0 it was also made 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>
|
|
|
|
<note>
|
|
<para>
|
|
<link linkend="language.oop5.autoload">Autoloading</link> is not
|
|
available if using PHP in &cli; interactive mode.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<!--}}}-->
|
|
|
|
<!--Built-in CLI Web Server: {{{-->
|
|
<section xml:id="features.commandline.webserver">
|
|
<title>Built-in web server</title>
|
|
|
|
<warning>
|
|
<para>
|
|
This web server was 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>
|
|
As of PHP 5.4.0, 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;</entr://bugs.php.net/bug.php?id=79314>
|
|
<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 <constant>PHP_CLI_SERVER_WORKERS</constant>
|
|
environment variable to the number of desired workers before starting
|
|
the server.
|
|
</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>
|
|
</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>
|
|
</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>
|
|
<row>
|
|
<entry><link linkend="ini.cli-server.color">cli_server.color</link></entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
<entry>Available since PHP 5.4.0.</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>boolean</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
|
|
-->
|