<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 299622 $ -->
<chapter xml:id="features.commandline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Using PHP from the command line</title>
 <titleabbrev>Command line usage</titleabbrev>
 
 <!--Introduction: {{{-->
 <section xml:id="features.commandline.introduction">
  <title>Introduction</title>
  
  <para>
   PHP supports a &cli.sapi; as of PHP 4.3.0. The main focus of this
   <acronym>SAPI</acronym> is for developing shell applications with PHP. There
   are quite a few differences between the &cli.sapi; and other
   <acronym>SAPI</acronym>s which are explained in this chapter. It is worth
   mentioning that &cli; and <acronym>CGI</acronym> are different
   <acronym>SAPI</acronym>s although they do share many of the same behaviors.
  </para>
  
  <para>
   The &cli.sapi; is enabled by default using
   <option role="configure">--enable-cli</option>, but may be disabled using
   the <option role="configure">--disable-cli</option> option when running
   <command>./configure</command>.
  </para>
  
  <para>
   The name, location and existence of the &cli;/<acronym>CGI</acronym>
   binaries will differ depending on how PHP is installed on your system. By
   default when executing <command>make</command>, both the <acronym>CGI</acronym>
   and &cli; are built and placed as <filename>sapi/cgi/php-cgi</filename> and
   <filename>sapi/cli/php</filename> respectively, in your PHP source directory.
   You will note that both are named <filename>php</filename>. What happens during
   <command>make install</command> depends on your configure line. If a module
   <acronym>SAPI</acronym> is chosen during configure, such as apxs, or the
   <option role="configure">--disable-cgi</option> option is used, the &cli; is
   copied to <filename>{PREFIX}/bin/php</filename> during
   <command>make install</command> otherwise the <acronym>CGI</acronym> is placed
   there. So, for example, if <option role="configure">--with--apxs </option> is
   in your configure line then the &cli; is copied to <filename>{PREFIX}/bin/php
   </filename> during <command>make install</command>. If you want to override
   the installation of the <acronym>CGI</acronym> binary, use <command>make
   install-cli</command> after <command>make install</command>. Alternatively you
   can specify <option role="configure">--disable-cgi</option> in your configure
   line.
  </para>
  
  <note>
   <para>
    Because both <option role="configure">--enable-cli</option> and
    <option role="configure">--enable-cgi</option> are enabled by default,
    simply having <option role="configure">--enable-cli</option> in your
    configure line does not necessarily mean the &cli; will be copied as
    <filename>{PREFIX}/bin/php</filename> during <command>make install</command>.
   </para>
  </note>
  
  <para>
   As of PHP 5, the &cli; binary is distributed in the main folder as <filename>
   php.exe</filename> on Windows. The <acronym>CGI</acronym> version is
   distributed as <filename>php-cgi.exe</filename>. Additionally, a <filename>
   php-win.exe</filename> is distributed if PHP is configured using
   <option role="configure">--enable-cli-win32</option>. This does the same as
   the &cli; version, except that it doesn't output anything and thus provides
   no console.
  </para>
  
  <note>
   <title>What SAPI do I have?</title>
   <para>
    From a shell, typing <command>php -v</command> will tell you
    whether <filename>php</filename> is <acronym>CGI</acronym> or &cli;. See
    also the function <function>php_sapi_name</function> and the constant
    <constant>PHP_SAPI</constant>.
   </para>
  </note>
  
  <note>
   <para>
    A Unix <literal>man</literal>ual page is available by typing <command>man
    php</command> in your shell environment.
   </para>
  </note>
 </section>
 <!--}}}-->
 
 <!--Differences: {{{-->
 <section xml:id="features.commandline.differences">
  <title>Differences to other <acronym>SAPI</acronym>s</title>
  
  <para>
   Remarkable differences of the &cli; <acronym>SAPI</acronym> compared to other
   <acronym>SAPI</acronym>s:
   <itemizedlist>
    <listitem>
     <para>
      Unlike the <acronym>CGI</acronym> <acronym>SAPI</acronym>, no headers are
      written to the output.
     </para>
     <para>
      Though the <acronym>CGI</acronym> <acronym>SAPI</acronym> provides a way
      to suppress HTTP headers, there's no equivalent switch to enable them in
      the &cli.sapi;.
     </para>
     <para>
      &cli; is started up in quiet mode by default, though the <option>-q</option>
      and <option>--no-header</option> switches are kept for compatibility so
      that you can use older <acronym>CGI</acronym> scripts.
     </para>
     <para>
      It does not change the working directory to that of the script.
      (<option>-C</option> and <option>--no-chdir</option> switches kept for
      compatibility)
     </para>
     <para>
      Plain text error messages (no <acronym>HTML</acronym> formatting).
     </para>
    </listitem>
    
    <listitem>
     <para>
      There are certain &php.ini; directives which are overridden by the
      &cli.sapi; because they do not make sense in shell environments:
     </para>
     <para>
      <table>
       <title>Overridden &php.ini; directives</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Directive</entry>
          <entry>&cli; <acronym>SAPI</acronym> default value</entry>
          <entry>Comment</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><link linkend="ini.html-errors">html_errors</link></entry>
          <entry>&false;</entry>
          <entry>
           It can be quite hard to read the error message in your shell when
           it's cluttered with all those meaningless <acronym>HTML</acronym>
           tags, therefore this directive defaults to &false;.
          </entry>
         </row>
         <row>
          <entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>
          <entry>&true;</entry>
          <entry>
           It is desired that any output coming from <function>print</function>,
           <function>echo</function> and friends is immediately written to the
           output and not cached in any buffer. You still can use
           <link linkend="ref.outcontrol">output buffering</link> if you want to
           defer or manipulate standard output.
          </entry>
         </row>
         <row>
          <entry><link linkend="ini.max-execution-time">max_execution_time</link></entry>
          <entry>0 (unlimited)</entry>
          <entry>
           Due to endless possibilities of using PHP in shell environments, the
           maximum execution time has been set to unlimited. Whereas
           applications written for the web are often executed very quickly,
           shell application tend to have a much longer execution time.
          </entry>
         </row>
         <row>
          <entry><link linkend="ini.register-argc-argv">register_argc_argv</link></entry>
          <entry>&true;</entry>
          <entry>
          <para>
           Because this setting is &true; you will always have access to
           <emphasis>argc</emphasis> (number of arguments passed to the 
           application) and <emphasis>argv</emphasis> (array of the actual
           arguments) in the &cli; <acronym>SAPI</acronym>.
          </para>
          <para>
           The PHP variables <varname>$argc</varname>
           and <varname>$argv</varname> are registered and filled in with the appropriate 
           values when using the &cli; <acronym>SAPI</acronym>. You can also go
           through <varname>$_SERVER</varname> or. Example:
           <varname>$_SERVER['argv']</varname>
          </para>
          </entry>
         </row>
         <row>
          <entry><link linkend="ini.output-buffering">output_buffering</link></entry>
          <entry>&false;</entry>
          <entry>
           <para>
            Altough the &php.ini; setting is hardcoded to &false; the
            <link linkend="book.outcontrol">Output buffering</link> functions
            are available.
           </para>
          </entry>
         </row>
         <row>
          <entry><link linkend="ini.max-input-time">max_input_time</link></entry>
          <entry>&false;</entry>
          <entry>
           <para>
            The PHP &cli; doesn't not support GET, POST or file uploads.
           </para>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
     <note>
      <para>
       These directives cannot be initialized with another value from the
       configuration file &php.ini; or a custom one (if specified). This is a
       limitation because those default values are applied after all
       configuration files have been parsed. However, their value can be changed
       during runtime (which does not make sense for all of those directives,
       e.g. <link linkend="ini.register-argc-argv">register_argc_argv</link>).
      </para>
     </note>
     <note>
      <para>
       It is recommended to set
       <link linkend="ini.ignore-user-abort">ignore_user_abort</link> for
       command line scripts. See <function>ignore_user_abort</function> for
       more info.
      </para>
     </note>
    </listitem>
    
    <listitem>
     <para>
      To ease working in the shell environment, a number of constants are
      defined for <link linkend="features.commandline.io-streams">I/O streams
      </link>.
     </para>
    </listitem>
    
    <listitem>
     <para>
      The &cli.sapi; does <emphasis role="strong">not</emphasis> change the
      current directory to the directory of the executed script!
     </para>
     <example>
      <title>
       Example showing the difference to the <acronym>CGI</acronym>
       <acronym>SAPI</acronym>:
      </title>
      <programlisting role="php">
<![CDATA[
<?php
// Our simple test application named test.php
echo getcwd(), "\n";
?>
]]>
      </programlisting>
      <para>
       When using the <acronym>CGI</acronym> version, the output is:
      </para>
      <screen>
<![CDATA[
$ pwd
/tmp

$ php -q another_directory/test.php
/tmp/another_directory
]]>
      </screen>
      <para>
       This clearly shows that PHP changes its current directory to the one of
       the executed script.
      </para>
      <para>
       Using the &cli.sapi; yields:
      </para>
      <screen>
<![CDATA[
$ pwd
/tmp

$ php -f another_directory/test.php
/tmp
]]>
      </screen>
      <para>
       This allows greater flexibility when writing shell tools in PHP.
      </para>
     </example>
     <note>
      <para>
       The <acronym>CGI</acronym> <acronym>SAPI</acronym> supports this
       &cli.sapi; behaviour by means of the <option>-C</option> switch when run
       from the command line.
      </para>
     </note>
    </listitem>
   </itemizedlist>
  </para>
 </section>
 <!--}}}-->
 
 <!--Options: {{{-->
 <section xml:id="features.commandline.options">
  <title>Command line options</title>
  <titleabbrev>Options</titleabbrev>
  
  <para>
   The list of command line options provided by the PHP binary can be queried
   anytime by running PHP with the <option>-h</option> switch:
   <screen>
<![CDATA[
Usage: php [options] [-f] <file> [--] [args...]
       php [options] -r <code> [--] [args...]
       php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

  -a               Run interactively
  -c <path>|<file> Look for php.ini file in this directory
  -n               No php.ini file will be used
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -f <file>        Parse and execute <file>.
  -h               This help
  -i               PHP information
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -r <code>        Run PHP <code> without using script tags <?..?>
  -B <begin_code>  Run PHP <begin_code> before processing input lines
  -R <code>        Run PHP <code> for every input line
  -F <file>        Parse and execute <file> for every input line
  -E <end_code>    Run PHP <end_code> after processing all input lines
  -H               Hide any passed arguments from external tools.
  -s               Output HTML syntax highlighted source.
  -v               Version number
  -w               Output source with stripped comments and whitespace.
  -z <file>        Load Zend extension <file>.

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

  --ini            Show configuration file names

  --rf <name>      Show information about function <name>.
  --rc <name>      Show information about class <name>.
  --re <name>      Show information about extension <name>.
  --ri <name>      Show configuration for extension <name>.
]]>
   </screen>
  </para>
  
  <para>
   <table>
    <title>Command line options</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Long Option</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>-a</entry>
       <entry>--interactive</entry>
       <entry>
        <para>
         Runs PHP interactively. For more information, see the <link
         linkend="features.commandline.interactive">Interactive shell</link>
         section.
        </para>
       </entry>
      </row>
      <row>
       <entry>-b</entry>
       <entry>--bindpath</entry>
       <entry>
        <para>
         Bind Path for external FASTCGI Server mode (<acronym>CGI</acronym>
         only).
        </para>
       </entry>
      </row>
      <row>
       <entry>-C</entry>
       <entry>--no-chdir</entry>
       <entry>
        <para>
         Do not chdir to the script's directory (<acronym>CGI</acronym> only).
        </para>
       </entry>
      </row>
      <row>
       <entry>-q</entry>
       <entry>--no-header</entry>
       <entry>
        <para>
         Quiet-mode. Suppress <acronym>HTTP</acronym> header output
         (<acronym>CGI</acronym> only).
        </para>
       </entry>
      </row>
      <row>
       <entry>-T</entry>
       <entry>--timing</entry>
       <entry>
        <para>
         Measure execution time of script repeated <varname>count</varname>
         times (<acronym>CGI</acronym> only).
        </para>
       </entry>
      </row>
      <row>
       <entry>-c</entry>
       <entry>--php-ini</entry>
       <entry>
        <para>
         This option can either specify a directory where to look for
         &php.ini; or specify a custom <literal>INI</literal> file
         (which does not need to be named &php.ini;), e.g.:
        </para>
        <para><informalexample>
         <screen>
<![CDATA[
$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php
]]>
         </screen>
        </informalexample></para>
        <para>
         If you don't specify this option, file is searched in
         <link linkend="configuration.file">default locations</link>.
        </para>
       </entry>
      </row>
      <row>
       <entry>-n</entry>
       <entry>--no-php-ini</entry>
       <entry>
        <para>
         Ignore &php.ini; at all.
        </para>
       </entry>
      </row>
      <row>
       <entry>-d</entry>
       <entry>--define</entry>
       <entry>
        <para>
         This option allows you to set a custom value for any of the configuration
         directives allowed in &php.ini;. The syntax is:
         <screen>
 <![CDATA[
 -d configuration_directive[=value]
 ]]>
         </screen>
        </para>
        <para><example>
         <screen>
<![CDATA[
# Omitting the value part will set the given configuration directive to "1"
$ php -d max_execution_time
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passing an empty value part will set the configuration directive to ""
php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# The configuration directive will be set to anything passed after the '=' character
$  php -d max_execution_time=20
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php
        -d max_execution_time=doesntmakesense
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"
]]>
         </screen>
        </example></para>
       </entry>
      </row>
      <row>
       <entry>-e</entry>
       <entry>--profile-info</entry>
       <entry>
        <para>
         Activate the extended information mode, to be used by a
         debugger/profiler.
        </para>
       </entry>
      </row>
      <row>
       <entry>-f</entry>
       <entry>--file</entry>
       <entry>
        <para>
         Parses and executes the given filename to the <option>-f</option>
         option. This switch is optional and can be left out. Only providing
         the filename to execute is sufficient.
        </para>
        <note>
         <para>
          To pass arguments to scripts the first argument needs to be
          <literal>--</literal>, otherwise PHP will interperate them as PHP
          options.
         </para>
        </note>
       </entry>
      </row>
      <row>
       <entry>-h and -?</entry>
       <entry>--help and --usage</entry>
       <entry>
        With this option, you can get information about the actual list of
        command line options and some one line descriptions about what they do.
       </entry>
      </row>
      <row>
       <entry>-i</entry>
       <entry>--info</entry>
       <entry>
        This command line option calls <function>phpinfo</function>, and prints
        out the results. If PHP is not working correctly, it is
        advisable to use <command>php -i</command> and see whether any error
        messages are printed out before or in place of the information tables.
        Beware that when using the <acronym>CGI</acronym> mode the output is in
        <acronym>HTML</acronym> and therefore quite huge.
       </entry>
      </row>
      <row>
       <entry>-l</entry>
       <entry>--syntax-check</entry>
       <entry>
        <para>
         This option provides a convenient way to only perform a syntax check
         on the given PHP code. On success, the text
         <literal>No syntax errors detected in &lt;filename&gt;</literal> is
         written to standard output and the shell return code is
         <literal>0</literal>. On failure, the text <literal>Errors parsing
         &lt;filename&gt;</literal> in addition to the internal parser error
         message is written to standard output and the shell return code is set
         to <literal>-1</literal>.
        </para>
        <para>
         This option won't find fatal errors (like undefined functions). Use
         <option>-f</option> if you would like to test for fatal errors too.
        </para>
        <note>
         <para>
          This option does not work together with the <option>-r</option>
          option.
         </para>
        </note>
       </entry>
      </row>
      <row>
       <entry>-m</entry>
       <entry>--modules</entry>
       <entry>
        <para><example>
         <title>Printing built in (and loaded) PHP and Zend modules</title>
         <screen>
<![CDATA[
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]
]]>
         </screen>
        </example></para>
       </entry>
      </row>
      <row>
       <entry>-r</entry>
       <entry>--run</entry>
       <entry>
        <para>
         This option allows execution of PHP right from
         within the command line. The PHP start and end tags
         (<literal>&lt;?php</literal> and <literal>?&gt;</literal>) are
         <emphasis role="strong">not needed</emphasis> and will cause a parser
         error if present.
        </para>
        <note>
         <para>
          Care has to be taken when using this form of PHP
          to not collide with command line variable substitution done by the
          shell.
         </para>
         <example>
          <title>Getting a syntax error when using double quotes</title>
          <screen>
<![CDATA[
$ php -r "$foo = get_defined_constants();"
PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

Parse error: syntax error, unexpected '=' in Command line code on line 1
]]>
          </screen>
         </example>
         <para>
          The problem here is that the sh/bash performs variable substitution
          even when using double quotes <literal>"</literal>. Since the
          variable <varname>$foo</varname> is unlikely to be defined, it
          expands to nothing which results in the code passed to
          PHP for execution actually reading:
         </para>
         <informalexample>
          <screen>
<![CDATA[
$ php -r " = get_defined_constants();"
]]>
          </screen>
         </informalexample>
         
         <para>
          The correct way would be to use single quotes <literal>'</literal>.
          Variables in single-quoted strings are not expanded
          by sh/bash.
         </para>
         <example>
          <title>Using single quotes to prevent the shell's variable
          substitution</title>
          <screen>
<![CDATA[
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]
]]>
          </screen>
         </example>
         <para>
          If you are using a shell different from sh/bash, you might experience
          further issues. Feel free to open a bug report at
          <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.
          One can still easily run into troubles when trying to get shell
          variables into the code or using backslashes for escaping. You've
          been warned.
         </para>
        </note>
        <note>
         <para>
          <option>-r</option> is available in the &cli.sapi; and not in the
          <emphasis>CGI</emphasis> <acronym>SAPI</acronym>.
         </para>
        </note>
        <note>
         <para>
          This option is meant for a very basic stuff. Thus some configuration
          directives (e.g. <link
          linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
          linkend="ini.auto-append-file">auto_append_file</link>) are ignored
          in this mode.
         </para>
        </note>
       </entry>
      </row>
      <row>
       <entry>-B</entry>
       <entry>--process-begin</entry>
       <entry>
        <para>
         PHP code to execute before processing stdin. Added in PHP 5.
        </para>
       </entry>
      </row>
      <row>
       <entry>-R</entry>
       <entry>--process-code</entry>
       <entry>
        <para>
         PHP code to execute for every input line. Added in PHP 5.
        </para>
        <para>
         There are two special variables available in this mode:
         <varname>$argn</varname> and <varname>$argi</varname>.
         <varname>$argn</varname> will contain the line PHP is processing at
         that moment, while <varname>$argi</varname> will contain the line
         number.
        </para>
       </entry>
      </row>
      <row>
       <entry>-F</entry>
       <entry>--process-file</entry>
       <entry>
        <para>
         PHP file to execute for every input line. Added in PHP 5.
        </para>
       </entry>
      </row>
      <row>
       <entry>-E</entry>
       <entry>--process-end</entry>
       <entry>
        <para>
         PHP code to execute after processing the input. Added in PHP 5.
        </para>
        <para><example>
         <title>Using the <option>-B</option>, <option>-R</option> and
          <option>-E</option> options to count the number of lines of a
          project.
         </title>
         <screen>
<![CDATA[
$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328
]]>
         </screen>
        </example></para>
       </entry>
      </row>
      <row>
       <entry>-s</entry>
       <entry>--syntax-highlight and --syntax-highlighting</entry>
       <entry>
        <para>
         Display colour syntax highlighted source.
        </para>
        <para>
         This option uses the internal mechanism to parse the file and produces
         a HTML highlighted version of it and writes it to
         standard output. Note that all it does it to generate a block of
         <literal>&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 stripped comments and whitespace.
        </para>
        <note>
         <para>
          This option does not work together with the <option>-r</option>
          option.
         </para>
        </note>
       </entry>
      </row>
      <row>
       <entry>-z</entry>
       <entry>--zend-extension</entry>
       <entry>
        <para>
         Load Zend extension. If only a filename is given, PHP tries to load
         this extension from the current default library path on your system
         (usually specified <filename>/etc/ld.so.conf</filename> on Linux
         systems).  Passing a filename with an absolute path information will
         not use the systems library search path. A relative filename with a
         directory information will tell PHP only to try to
         load the extension relative to the current directory.
        </para>
       </entry>
      </row>
      <row>
       <entry></entry>
       <entry>--ini</entry>
       <entry>
        <para>
         Shows configuration file names and scanned directories. Available as
         of PHP 5.2.3.
         <example>
          <title><literal>--ini</literal> example</title>
          <programlisting role="shell">
<![CDATA[
$ php --ini
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)
]]>
          </programlisting>
         </example>
        </para>
       </entry>
      </row>
      <row>
       <entry>--rf</entry>
       <entry>--rfunction</entry>
       <entry>
        <para>
         Shows information about the given function or class method (e.g.
         number and name of the parameters). Available as of PHP 5.1.2.
        </para>
        <para>
         This option is only available if PHP was compiled with
         <link linkend="book.reflection">Reflection</link> support.
        </para>
        <para>
         <example>
          <title>basic <literal>--rf</literal> usage</title>
          <programlisting role="shell">
<![CDATA[
$ php --rf var_dump
Function [ <internal> public function var_dump ] {

  - Parameters [2] {
    Parameter #0 [ <required> $var ]
    Parameter #1 [ <optional> $... ]
  }
}
]]>
          </programlisting>
         </example>
        </para>
       </entry>
      </row>
      <row>
       <entry>--rc</entry>
       <entry>--rclass</entry>
       <entry>
        <para>
         Show information about the given class (list of constants, properties
         and methods). Available as of PHP 5.1.2.
        </para>
        <para>
         This option is only available if PHP was compiled with
         <link linkend="book.reflection">Reflection</link> support.
        </para>
        <para>
         <example>
          <title><literal>--rc</literal> example</title>
          <programlisting role="shell">
<![CDATA[
$ php --rc Directory
Class [ <internal:standard> class Directory ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [3] {
    Method [ <internal> public method close ] {
    }

    Method [ <internal> public method rewind ] {
    }

    Method [ <internal> public method read ] {
    }
  }
}
]]>
          </programlisting>
         </example>
        </para>
       </entry>
      </row>
      <row>
       <entry>--re</entry>
       <entry>--rextension</entry>
       <entry>
        <para>
         Show information about the given extension (list of &php.ini; options,
         defined functions, constants and classes). Available as of PHP 5.1.2.
        </para>
        <para>
         This option is only available if PHP was compiled with
         <link linkend="book.reflection">Reflection</link> support.
        </para>
        <para>
         <example>
          <title><literal>--re</literal> example</title>
          <programlisting role="shell">
<![CDATA[
$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {

  - Functions {
    Function [ <internal> function json_encode ] {
    }
    Function [ <internal> function json_decode ] {
    }
  }
}
]]>
          </programlisting>
         </example>
        </para>
       </entry>
      </row>
      <row>
       <entry>--ri</entry>
       <entry>--rextinfo</entry>
       <entry>
        <para>
         Shows the configuration information for the given extension (the same
         information that is returned by <function>phpinfo</function>).
         Available as of PHP 5.2.2. The core configuration information
         are available using "main" as extension name.
        </para>
        <para>
         <example>
          <title><literal>--ri</literal> example</title>
          <programlisting role="shell">
<![CDATA[
$ php --ri date

date

date/time support => enabled
"Olson" Timezone Database Version => 2009.20
Timezone Database => internal
Default timezone => Europe/Oslo

Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.930972 => 59.930972
date.default_longitude => 10.776699 => 10.776699
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333
]]>
          </programlisting>
         </example>
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  
  <note>
   <para>
    Options <literal>-rBRFEH</literal>, <literal>--ini</literal> and
    <literal>--r[fcei]</literal> are available only in &cli;.
   </para>
  </note>
 </section>
 <!--}}}-->
 
 <!--Usage: {{{-->
 <section xml:id="features.commandline.usage">
  <title>Executing PHP files</title>
  <titleabbrev>Usage</titleabbrev>
  
  <para>
   The &cli.sapi; has three different ways of getting the PHP code you want to
   execute:
   <orderedlist>
    <listitem>
     <para>
      Telling PHP to execute a certain file.
     </para>
     <informalexample>
      <screen>
<![CDATA[
$ php my_script.php

$ php -f my_script.php
]]>
      </screen>
     </informalexample>
     <para>
      Both ways (whether using the <option>-f</option> switch or not) execute
      the file <filename>my_script.php</filename>. You can choose any file to
      execute, and your PHP scripts do not have to end with the
      <literal>.php</literal> extension but can have any name or extension
      you wish.
     </para>
     <note>
      <para>
       If you need to pass arguments to your scripts you need to pass
       <literal>--</literal> as the first argument when using the
       <option>-f</option> switch.
      </para>
     </note>
    </listitem>
    <listitem>
     <para>
      Pass the PHP code to execute directly on the command line.
     </para>
     <informalexample>
      <screen>
<![CDATA[
$ php -r 'print_r(get_defined_constants());'
]]>
      </screen>
     </informalexample>
     <para>
      Special care has to be taken in regards of shell variable substitution and
      quoting usage.
     </para>
     <note>
      <para>
       Read the example carefully, there are no beginning or ending tags! The
       <option>-r</option> switch simply does not need them. Using them will
       lead to a parser error.
      </para>
     </note>
    </listitem>
    <listitem>
     <para>
      Provide the PHP code to execute via standard input
      (<literal>stdin</literal>).
     </para>
     <para>
      This gives the powerful ability to dynamically create PHP code and feed it
      to the binary, as shown in this (fictional) example:
     </para>
     <informalexample>
      <screen>
<![CDATA[
$ some_application | some_filter | php | sort -u > final_output.txt
]]>
      </screen>
     </informalexample>
    </listitem>
   </orderedlist>
   You cannot combine any of the three ways to execute code.
  </para>
  
  <para>
   Like every shell application, the PHP binary accepts a number of arguments
   but your PHP script can also receive arguments. The number of arguments which
   can be passed to your script is not limited by PHP (the shell has a certain
   size limit in the number of characters which can be passed; usually you won't
   hit this limit). The arguments passed to your script are available in the
   global array <varname>$argv</varname>. The zero index always contains the
   script name (which is <literal>-</literal> in case the PHP codeis coming from
   either standard input or from the command line switch <option>-r</option>).
   The second registered global variable is <varname>$argc</varname> which
   contains the number of elements in the <varname>$argv</varname> array
   (<emphasis role="strong">not</emphasis> the number of arguments passed to the
   script).
  </para>
  
  <para>
   As long as the arguments you want to pass to your script do not start with
   the <literal>-</literal> character, there's nothing special to watch out for.
   Passing an argument to your script which starts with a <literal>-</literal>
   will cause trouble because PHP itself thinks it has to handle it. To prevent
   this, use the argument list separator <literal>--</literal>. After this
   separator has been parsed by PHP, every argument following it is passed
   untouched to your script.
  </para>
  
  <informalexample>
   <screen>
<![CDATA[
# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# This will pass the '-h' argument to your script and prevent PHP from showing it's usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}
]]>
   </screen>
  </informalexample>
  
  <para>
   However on Unix systems, there's another way of using PHP for shell
   scripting. You can write a script where the first line starts with
   <literal>#!/usr/bin/php</literal> (substitute with the path to your PHP &cli;
   binary if necessary. Following this you can place normal PHP code included
   within the PHP starting and end tags. Once you have set the execution
   attributes of the file appropriately (e.g. <command>chmod +x test</command>)
   your script can be executed like a normal shell or perl script:
  </para>
  
  <example>
   <title>Execute PHP script as shell script</title>
   <programlisting role="php">
<![CDATA[
#!/usr/bin/php
<?php
var_dump($argv);
?>
]]>
   </programlisting>
   <para>
     Assuming this file is named <filename>test</filename> in the current
     directory, we can now do the following:
   </para>
   <screen>
<![CDATA[
$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}
]]>
   </screen>
  </example>
  
  <para>
   As you see, in this case no care needs to be taken when passing parameters
   which start with <literal>-</literal> to your script.
  </para>
  
  <para>
   The PHP executable can be used to run PHP scripts absolutely independent
   from the web server. If you are on a Unix system, you should add a special
   first line to your PHP script, and make it executable, so the system will
   know, what program should run the script. On a Windows platform you can
   associate <filename>php.exe</filename> with the double click option of the
   <literal>.php</literal> files, or you can make a batch
   file to run the script through PHP. The first line added to the script to
   work on Unix won't hurt on Windows, so you can write cross platform programs
   this way. A simple example of writing a command line PHP program can be
   found below.
  </para>
  
  <para>
   <example>
    <title>Script intended to be run from command line (script.php)</title>
    <programlisting role="php">
<![CDATA[
#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

This is a command line PHP script with one option.

  Usage:
  <?php echo $argv[0]; ?> <option>

  <option> can be some word you would like
  to print out. With the --help, -help, -h,
  or -? options, you can get this help.

<?php
} else {
    echo $argv[1];
}
?>
]]>
    </programlisting>
   </example>
  </para>
  
  <para>
   In the script above, we used the special first line to indicate that this
   file should be run by PHP. We work with a &cli; version here, so there will
   be no <acronym>HTTP</acronym> header printouts. There are two variables you
   can use while writing command line applications with PHP:
   <varname>$argc</varname> and <varname>$argv</varname>. The first is the
   number of arguments plus one (the name of the script running). The second is
   an array containing the arguments, starting with the script name as number
   zero (<varname>$argv[0]</varname>).
  </para>
  
  <para>
   In the program above we checked if there are less or more than one arguments.
   Also if the argument was <option>--help</option>, <option>-help</option>,
   <option>-h</option> or <option>-?</option>, we printed out the help message,
   printing the script name dynamically. If we received some other argument we
   echoed that out.
  </para>
  
  <para>
   If you would like to run the above script on Unix, you need to make it
   executable, and simply call it as <command>script.php echothis</command> or
   <command>script.php -h</command>. On Windows, you can make a batch file for
   this task:
  </para>
  
  <para>
   <example>
    <title>Batch file to run a command line PHP script (script.bat)</title>
    <programlisting role="shell">
<![CDATA[
@echo OFF
"C:\php\php.exe" script.php %*
]]>
    </programlisting>
   </example>
  </para>
  
  <para>
   Assuming you named the above program <filename>script.php</filename>, and you
   have your &cli; <filename>php.exe</filename> in <filename>C:\php\php.exe
   </filename> this batch file will run it for you with your added options:
   <command>script.bat echothis</command> or <command>script.bat -h</command>.
  </para>
  
  <para>
   See also the <link linkend="ref.readline">Readline</link> extension
   documentation for more functions you can use to enhance your command line
   applications in PHP.
  </para>
  
  <para>
   If you are on Windows, PHP can be configured to run without the need to
   supply the <filename>C:\php\php.exe</filename> or the <literal>.php</literal>
   extension, as descibed in <link linkend="install.windows.commandline">Command
   Line PHP on Microsoft Windows</link>.
  </para>
 </section>
 <!--}}}-->
 
 <!--I/O Streams: {{{-->
 <section xml:id="features.commandline.io-streams">
  <title>Input/output streams</title>
  <titleabbrev>I/O streams</titleabbrev>
  
  <para>
   The &cli.sapi; defines a few constants for I/O streams to make programming
   for the command line a bit easier.
  </para>
  
  <para>
   <table>
    <title>CLI specific Constants</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Constant</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><constant>STDIN</constant></entry>
       <entry>
        <para>An already opened stream to <literal>stdin</literal>. This saves
       opening it with
       <programlisting role="php">
<![CDATA[
<?php
$stdin = fopen('php://stdin', 'r');
?>
]]>
       </programlisting>
       If you want to read single line from <literal>stdin</literal>, you can
       use
       <programlisting role="php">
<![CDATA[
<?php
$line = trim(fgets(STDIN)); // reads one line from STDIN
fscanf(STDIN, "%d\n", $number); // reads number from STDIN
?>
]]>
       </programlisting>
       </para></entry>
      </row>
      <row>
       <entry><constant>STDOUT</constant></entry>
       <entry><para>
       An already opened stream to <literal>stdout</literal>. This saves
       opening it with
       <programlisting role="php">
<![CDATA[
<?php
$stdout = fopen('php://stdout', 'w');
?>
]]>
       </programlisting>
       </para></entry>
      </row>
      <row>
       <entry><constant>STDERR</constant></entry>
       <entry>
        <para>
         An already opened stream to <literal>stderr</literal>.
         This saves opening it with
         <programlisting role="php">
<![CDATA[
<?php
$stderr = fopen('php://stderr', 'w');
?>
]]>
         </programlisting>
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  
  <para>
   Given the above, you don't need to open e.g. a stream for
   <literal>stderr</literal> yourself but simply use the constant instead of
   the stream resource:
   <programlisting role="shell">
<![CDATA[
php -r 'fwrite(STDERR, "stderr\n");'
]]>
   </programlisting>
   You do not need to explicitly close these streams, as they are closed
   automatically by PHP when your script ends.
  </para>
  
  <note>
   <para>
    These constants are not available in case of reading PHP script from
    <literal>stdin</literal>.
   </para>
  </note>
 </section>
 <!--}}}-->

 <!--Interactive shell: {{{-->
 <section xml:id="features.commandline.interactive">
  <title>Interactive shell</title>

  <para>
   As of PHP 5.1.0, the &cli.sapi; provides an interactive shell using the
   <option>-a</option> option if PHP is compiled with the <option
   role="configure">--with-readline</option> option.
  </para>

  <para>
   Using the interactive shell you are able to type PHP code and have it
   executed directly.
  </para>

  <example>
   <title>Executing code using the interactive shell</title> 
   <programlisting role="shell">
<![CDATA[
$ php -a
Interactive shell

php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php > 
]]>
   </programlisting>
  </example>

  <para>
   The interactive shell also features tab completion for functions,
   constants, class names, variables, static method calls and class
   constants.
  </para>

  <example>
   <title>Tab completion</title>
   <simpara>
    Pressing the tab key twice when there are multiple possible completions
    will result in a list of these completions:
   </simpara>
   <programlisting role="shell">
<![CDATA[
php > strp[TAB][TAB]
strpbrk   strpos    strptime  
php > strp
]]>
   </programlisting>
   <simpara>
    When there is only one possible completion, pressing tab once will
    complete the rest on the same line:
   </simpara>
   <programlisting role="shell">
<![CDATA[
php > strpt[TAB]ime(
]]>
   </programlisting>
   <simpara>
    It is also possible doing completion on things that have been defined
    during the interactive shell session:
   </simpara>
   <programlisting role="shell">
<![CDATA[
php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName
]]>
   </programlisting>
  </example>

  <para>
   The interactive shell stores your history and can be accessed using the up
   and down keys. The history is saved in the
   <filename>~/.php_history</filename> file.
  </para>

  <!-- NOT YET AVAILABLE, UNCOMMENT AND FIX VERSIONS WHEN RELEASED
  <para>
   As of [whatever becomes the next version], the &cli.sapi; provides
   two new &php.ini; settings: <parameter>cli.pager</parameter> and
   <parameter>cli.prompt</parameter>. The <parameter>cli.pager</parameter>
   setting allows an external program (such as <filename>less</filename>) to
   act as a pager for the output instead of being displayed directly on the
   screen. The <parameter>cli.prompt</parameter> setting makes it possible to
   change the <literal>php &gt;</literal> prompt.
  </para>

  <para>
   In [whatever becoems the next version] it was also made possible setting
   &php.ini; settings in the interactive shell using a shorthand notation.
  </para>

  <example>
   <title>Setting &php.ini; settings in the interactive shell</title>
   <simpara>
    The <parameter>cli.prompt</parameter> setting:
   </simpara>
   <programlisting role="shell">
<![CDATA[
php > #cli.prompt=hello world :> 
hello world :> 
]]>
   </programlisting>
   <simpara>
    Using backticks it is possible to have PHP code executed in the prompt:
   </simpara>
   <programlisting role="shell">
<![CDATA[
php > #cli.prompt=`echo date('H:i:s');` php > 
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php > 
]]>
   </programlisting>
   <simpara>
    Setting the pager to <filename>less</filename>:
   </simpara>
   <programlisting role="shell">
<![CDATA[
php > #cli.pager=less
php > phpinfo();
(output displayed in less)
php > 
]]>
   </programlisting>
  </example>

  <para>
   The <parameter>cli.prompt</parameter> setting supports a few escape
   sequences:
   <table>
    <title><parameter>cli.prompt</parameter> escape sequences</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Sequence:</entry>
       <entry>Description:</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>\e</literal></entry>
       <entry>
        Used for adding colors to the prompt. An example could be
        <literal>\e[032m\v \e[031m\b \e[34m\> \e[0m</literal>
       </entry>
      </row>
      <row>
       <entry><literal>\v</literal></entry>
       <entry>The PHP version.</entry>
      </row>
      <row>
       <entry><literal>\b</literal></entry>
       <entry>
        Indicates which block PHP is in. For instance <literal>/*</literal> to
        indicate being inside a multi-line comment. The outer scope is denoted by
        <literal>php</literal>.
       </entry>
      </row>
      <row>
       <entry><literal>\&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>

  <note>
   <para>
    <link linkend="language.oop5.autoload">Autoloading</link> is not
    available if using PHP in &cli; interactive mode.
   </para>
  </note>
 </section>
 <!--}}}-->
 
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=marker fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->