commandline.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" annotations="chunk:false">
  <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>
          <warning>
           <para>
            The presence of <varname>$argv</varname> or <varname>$_SERVER['argv']</varname>
            is not a reliable indication that a script is being run from the
            command line because they may be set in other contexts when
            <link linkend="ini.register-argc-argv">register_argc_argv</link> is enabled.
            The value returned by <function>php_sapi_name</function> should be checked
            instead.
            <informalexample>
             <programlisting role="php">
<![CDATA[
<?php

if (php_sapi_name() === 'cli') {
    echo "This is being run from the command line!\n";
}
]]>
             </programlisting>
            </informalexample>
           </para>
          </warning>
          </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>
         <title>Example of using <literal>-d</literal> to set an INI setting</title>
         <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>
         Syntax check but do not execute the given PHP code.
         The input from standard input will be processed if no filenames are specified,
         otherwise each filename will be checked.
         On success, the text
         <literal>No syntax errors detected in &lt;filename&gt;</literal> is
         written to standard output.
         On failure, the text <literal>Errors parsing &lt;filename&gt;</literal>
         is written to standard output in addition to the internal parser error.
         If any failures are found in the specified files (or standard input),
         the shell return code is set to <literal>-1</literal>, otherwise the
         shell return code is set to <literal>0</literal>.
        </para>
        <para>
         This option won't find fatal errors (like undefined functions) that
         require executing the code.
        </para>
        <note>
         <para>
          Prior to PHP 8.3.0, it was only possible to specify one filename to
          be checked.
         </para>
        </note>
        <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>&lt;?php</literal> and
         <literal>?&gt;</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>&lt;code&gt; [...] &lt;/code&gt;</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 <constant>STDIN</constant>.
  </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="winbat">
<![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>

  <simpara>
   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.
   As of PHP 8.4.0, the path to the history file can be set using the
   <envar>PHP_HISTFILE</envar> environment variable.
  </simpara>

  <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 &gt;</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>\&gt;</literal></entry>
       <entry>
        Indicates the prompt character. By default this is
        <literal>&gt;</literal>, but changes when the shell is inside an
        unterminated block or string. Possible characters are: <literal>' " {
        ( &gt;</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
    <keycombo action='simul'>
     <keycap>CTRL</keycap>
     <keycap>D</keycap>
    </keycombo>
    (POSIX) or
    <keycombo action='simul'>
     <keycap>CTRL</keycap>
     <keycap>Z</keycap>
    </keycombo>
    followed by <keycap>ENTER</keycap> (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:
   <simplelist type="inline">
    <member><literal>.3gp</literal></member>
    <member><literal>.apk</literal></member>
    <member><literal>.avi</literal></member>
    <member><literal>.bmp</literal></member>
    <member><literal>.css</literal></member>
    <member><literal>.csv</literal></member>
    <member><literal>.doc</literal></member>
    <member><literal>.docx</literal></member>
    <member><literal>.flac</literal></member>
    <member><literal>.gif</literal></member>
    <member><literal>.gz</literal></member>
    <member><literal>.gzip</literal></member>
    <member><literal>.htm</literal></member>
    <member><literal>.html</literal></member>
    <member><literal>.ics</literal></member>
    <member><literal>.jpe</literal></member>
    <member><literal>.jpeg</literal></member>
    <member><literal>.jpg</literal></member>
    <member><literal>.js</literal></member>
    <member><literal>.kml</literal></member>
    <member><literal>.kmz</literal></member>
    <member><literal>.m4a</literal></member>
    <member><literal>.mov</literal></member>
    <member><literal>.mp3</literal></member>
    <member><literal>.mp4</literal></member>
    <member><literal>.mpeg</literal></member>
    <member><literal>.mpg</literal></member>
    <member><literal>.odp</literal></member>
    <member><literal>.ods</literal></member>
    <member><literal>.odt</literal></member>
    <member><literal>.oga</literal></member>
    <member><literal>.ogg</literal></member>
    <member><literal>.ogv</literal></member>
    <member><literal>.pdf</literal></member>
    <member><literal>.png</literal></member>
    <member><literal>.pps</literal></member>
    <member><literal>.pptx</literal></member>
    <member><literal>.qt</literal></member>
    <member><literal>.svg</literal></member>
    <member><literal>.swf</literal></member>
    <member><literal>.tar</literal></member>
    <member><literal>.text</literal></member>
    <member><literal>.tif</literal></member>
    <member><literal>.txt</literal></member>
    <member><literal>.wav</literal></member>
    <member><literal>.webm</literal></member>
    <member><literal>.wmv</literal></member>
    <member><literal>.xls</literal></member>
    <member><literal>.xlsx</literal></member>
    <member><literal>.xml</literal></member>
    <member><literal>.xsl</literal></member>
    <member><literal>.xsd</literal></member>
    <member><literal>.zip</literal></member>
   </simplelist>
   .
  </para>

  <simpara>
   As of PHP 7.4.0, the built-in webserver can be configured 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.
  </simpara>
  <note>
   <simpara>This feature is not supported on Windows.</simpara>
  </note>
  <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>

  <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><constant>INI_ALL</constant></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
-->