Sophie: php-manual-en-4.3.0-2mdk noarch

php-manual-en-4.3.0-2mdk.noarch.rpm

<HTML
><HEAD
><TITLE
>Using PHP from the command line</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Features"
HREF="features.html"><LINK
REL="PREVIOUS"
TITLE="Functions restricted/disabled by safe mode"
HREF="features.safe-mode.functions.html"><LINK
REL="NEXT"
TITLE="Function Reference"
HREF="funcref.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="features.safe-mode.functions.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="funcref.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="features.commandline"
>Chapter 23. Using PHP from the command line</A
></H1
><P
>&#13;  As of version 4.3.0, <TT
CLASS="literal"
>PHP</TT
> supports a new
  <TT
CLASS="literal"
>SAPI</TT
> type (Server Application Programming Interface)
  named <TT
CLASS="literal"
>CLI</TT
> which means <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Command Line
  Interface</I
></SPAN
>. As the name implies, this <TT
CLASS="literal"
>SAPI</TT
> type
  main focus is on developing shell (or desktop as well) applications with
  <TT
CLASS="literal"
>PHP</TT
>.  There are quite a few differences between the
  <TT
CLASS="literal"
>CLI SAPI</TT
> and other <TT
CLASS="literal"
>SAPI</TT
>s which are
  explained in this chapter.  It's worth mentioning
  that <TT
CLASS="literal"
>CLI</TT
> and <TT
CLASS="literal"
>CGI</TT
> are different
  SAPI's although they do share many of the same behaviors.
 </P
><P
>&#13;  The <TT
CLASS="literal"
>CLI SAPI</TT
> was released for the first time with
  <TT
CLASS="literal"
>PHP 4.2.0</TT
>, but was still experimental and had
  to be explicitly enabled with <TT
CLASS="literal"
>--enable-cli</TT
> when running
  <TT
CLASS="literal"
>./configure</TT
>.  Since <TT
CLASS="literal"
>PHP 4.3.0</TT
> the
  <TT
CLASS="literal"
>CLI SAPI</TT
> is no longer experimental and the option
  <TT
CLASS="literal"
>--enable-cli</TT
> is on by default.  You may use
  <TT
CLASS="literal"
>--disable-cli</TT
> to disable it.
 </P
><P
>&#13;  As of PHP 4.3.0, the name, location and existence of the CLI/CGI binaries
  will differ depending on how PHP is installed on your system.  By default
  when executing <TT
CLASS="literal"
>make</TT
>, both the CGI and CLI are built and
  placed as <TT
CLASS="literal"
>sapi/cgi/php</TT
> and <TT
CLASS="literal"
>sapi/cli/php</TT
> 
  respectively, in your php source directory.  You will note that both are
  named <TT
CLASS="literal"
>php</TT
>. What happens during <TT
CLASS="literal"
>make
  install</TT
> depends on your configure 
  line.  If a module SAPI is chosen during configure, such as apxs, or the
  <TT
CLASS="literal"
> --disable-cgi</TT
> option is used, the CLI is copied to
  <TT
CLASS="literal"
>{PREFIX}/bin/php</TT
> during <TT
CLASS="literal"
>make install</TT
>
  otherwise the CGI is placed there.  So, for example, if <TT
CLASS="literal"
>--with--apxs
  </TT
> is in your configure line then the CLI is copied to
  <TT
CLASS="literal"
>{PREFIX}/bin/php</TT
> during <TT
CLASS="literal"
>make
  install</TT
>. If you want to override the installation of the CGI
  binary, use <TT
CLASS="literal"
>make install-cli</TT
> after <TT
CLASS="literal"
>make
  install</TT
>.  Alternatively you can specify <TT
CLASS="literal"
>--disable-cgi
  </TT
> in your configure line.
 </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
   Because both <TT
CLASS="literal"
>--enable-cli</TT
> and <TT
CLASS="literal"
>&#13;   --enable-cgi</TT
> are enabled by default, simply having
   <TT
CLASS="literal"
>--enable-cli</TT
> in your configure line does
   not necessarily mean the CLI will be copied as <TT
CLASS="literal"
>&#13;   {PREFIX}/bin/php</TT
> during <TT
CLASS="literal"
>make install</TT
>.
  </P
></BLOCKQUOTE
></DIV
><P
>&#13;  The windows package distributes the CGI as php.exe and has a folder named
  cli with the CLI in it, so: <TT
CLASS="literal"
>cli/php.exe</TT
>.
 </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>What SAPI do I have?: </B
>
   From a shell, typing <TT
CLASS="literal"
>php -v</TT
> will tell you
   whether <TT
CLASS="literal"
>php</TT
> is CGI or CLI.  See also the function
   <A
HREF="function.php-sapi-name.html"
><B
CLASS="function"
>php_sapi_name()</B
></A
> and the constant <TT
CLASS="constant"
><B
>&#13;   PHP_SAPI</B
></TT
>.
  </P
></BLOCKQUOTE
></DIV
><P
>&#13;  Remarkable differences of the <TT
CLASS="literal"
>CLI SAPI</TT
> compared to other
  <TT
CLASS="literal"
>SAPI</TT
>s:
  <P
></P
><UL
><LI
><P
>&#13;     Unlike the <TT
CLASS="literal"
>CGI SAPI</TT
>, no headers are written to the
     output.
    </P
><P
>&#13;     Though the <TT
CLASS="literal"
>CGI SAPI</TT
> provides a way to suppress HTTP
     headers, there's no equivalent switch to enable them in the <TT
CLASS="literal"
>CLI
     SAPI</TT
>.
    </P
><P
>&#13;     CLI is started up in quiet mode by default, though the <TT
CLASS="literal"
>-q</TT
>
     switch is kept for compatibility so that you can use older CGI scripts.
    </P
><P
>&#13;     It does not change the working directory to that of the script.
     (<TT
CLASS="literal"
>-C</TT
> switch kept for compatibility)
    </P
><P
>&#13;     Plain text error messages (no HTML formatting).
    </P
></LI
><LI
><P
>&#13;     There are certain <TT
CLASS="filename"
>php.ini</TT
> directives which are overriden by the <TT
CLASS="literal"
>CLI
     SAPI</TT
> because they do not make sense in shell environments:
     <DIV
CLASS="table"
><A
NAME="AEN6505"
></A
><P
><B
>Table 23-1. Overriden <TT
CLASS="filename"
>php.ini</TT
> directives</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Directive</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>CLI SAPI</TT
> default value</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Comment</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="ref.errorfunc.html#ini.html-errors"
>html_errors</A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>FALSE</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;          It can be quite hard to read the error message in your shell when
          it's cluttered with all those meaningless <TT
CLASS="literal"
>HTML</TT
>
          tags, therefore this directive defaults to <TT
CLASS="constant"
><B
>FALSE</B
></TT
>.
         </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="ref.outcontrol.html#ini.implicit-flush"
>implicit_flush</A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>TRUE</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;          It is desired that any output coming from
          <A
HREF="function.print.html"
><B
CLASS="function"
>print()</B
></A
>, <A
HREF="function.echo.html"
><B
CLASS="function"
>echo()</B
></A
> and friends is
          immediately written to the output and not cached in any buffer. You
          still can use <A
HREF="ref.outcontrol.html"
>output buffering</A
>
          if you want to defer or manipulate standard output.
         </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="ref.info.html#ini.max-execution-time"
>max_execution_time</A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>0 (unlimited)</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;          Due to endless possibilities of using <TT
CLASS="literal"
>PHP</TT
> 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.
         </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="configuration.directives.html#ini.register-argc-argv"
>register_argc_argv</A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>TRUE</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;         <P
>&#13;          Because this setting is <TT
CLASS="constant"
><B
>TRUE</B
></TT
> you will always have access to
          <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>argc</I
></SPAN
> (number of arguments passed to the 
          application) and <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>argv</I
></SPAN
> (array of the actual
          arguments) in the <TT
CLASS="literal"
>CLI SAPI</TT
>.
         </P
>
         <P
>&#13;          As of PHP 4.3.0, the <TT
CLASS="literal"
>PHP</TT
> variables <TT
CLASS="literal"
>$argc</TT
>
          and <TT
CLASS="literal"
>$argv</TT
> are registered and filled in with the appropriate 
          values when using the <TT
CLASS="literal"
>CLI SAPI</TT
>. Prior to this version,
          the creation of these variables behaved as they do in
          <TT
CLASS="literal"
>CGI</TT
> and <TT
CLASS="literal"
>MODULE</TT
> versions
          which requires the PHP directive
          <A
HREF="configuration.directives.html#ini.register-globals"
>register_globals</A
> to
          be <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>on</I
></SPAN
>.  Regardless of version or register_globals
          setting, you can always go through either 
          <A
HREF="reserved.variables.html#reserved.variables.server"
>$_SERVER</A
> or 
          <TT
CLASS="varname"
>$HTTP_SERVER_VARS</TT
>.  Example:
          <TT
CLASS="varname"
>$_SERVER['argv']</TT
>
         </P
>
         </TD
></TR
></TBODY
></TABLE
></DIV
>
    </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
      These directives cannot be initialized with another value from the
      configuration file <TT
CLASS="filename"
>php.ini</TT
> 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. <A
HREF="configuration.directives.html#ini.register-argc-argv"
>register_argc_argv</A
>).
     </P
></BLOCKQUOTE
></DIV
></LI
><LI
><P
>&#13;     To ease working in the shell environment, the following constants
     are defined:
     <DIV
CLASS="table"
><A
NAME="AEN6568"
></A
><P
><B
>Table 23-2. CLI specific Constants</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Constant</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>STDIN</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;         An already opened stream to <TT
CLASS="literal"
>stdin</TT
>. This saves
         opening it with
         <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>$stdin = fopen('php://stdin', 'r');</PRE
></TD
></TR
></TABLE
>
         </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>STDOUT</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;         An already opened stream to <TT
CLASS="literal"
>stdout</TT
>. This saves
         opening it with
         <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>$stdout = fopen('php://stdout', 'w');</PRE
></TD
></TR
></TABLE
>
         </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>STDERR</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;         An already opened stream to <TT
CLASS="literal"
>stderr</TT
>. This saves
         opening it with
         <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>$stderr = fopen('php://stderr', 'w');</PRE
></TD
></TR
></TABLE
>
         </TD
></TR
></TBODY
></TABLE
></DIV
>
    </P
><P
>&#13;     Given the above, you don't need to open e.g. a stream for
     <TT
CLASS="literal"
>stderr</TT
> yourself but simply use the constant instead of
     the stream resource:
     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>php -r 'fwrite(STDERR, "stderr\n");'</PRE
></TD
></TR
></TABLE
>
     You do not need to explicitly close these streams, as they are closed
     automatically by <TT
CLASS="literal"
>PHP</TT
> when your script ends.
    </P
></LI
><LI
><P
>&#13;     The <TT
CLASS="literal"
>CLI SAPI</TT
> does <SPAN
CLASS="strong"
><B
CLASS="emphasis"
>not</B
></SPAN
> change the current directory to the directory
     of the executed script!
    </P
><P
>&#13;     Example showing the difference to the <TT
CLASS="literal"
>CGI SAPI</TT
>:
     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?php
    /* Our simple test application named test.php*/
    echo getcwd(), "\n";
?&#62;</PRE
></TD
></TR
></TABLE
>
    </P
><P
>&#13;     When using the <TT
CLASS="literal"
>CGI</TT
> version, the output is:
     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ pwd
/tmp

$ php -q another_directory/test.php
/tmp/another_directory</PRE
></TD
></TR
></TABLE
>
     This clearly shows that <TT
CLASS="literal"
>PHP</TT
> changes its current
     directory to the one of the executed script.
    </P
><P
>&#13;     Using the <TT
CLASS="literal"
>CLI SAPI</TT
> yields:
     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ pwd
/tmp

$ php -f another_directory/test.php
/tmp</PRE
></TD
></TR
></TABLE
>
     This allows greater flexibility when writing shell tools in
     <TT
CLASS="literal"
>PHP</TT
>.
    </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
      The <TT
CLASS="literal"
>CGI SAPI</TT
> supports the <TT
CLASS="literal"
>CLI SAPI</TT
>
      behaviour by means of the <TT
CLASS="literal"
>-C</TT
> switch when run from the
      command line.
     </P
></BLOCKQUOTE
></DIV
></LI
></UL
>
 </P
><P
>&#13;  The list of command line options provided by the <TT
CLASS="literal"
>PHP</TT
>
  binary can be queried anytime by running <TT
CLASS="literal"
>PHP</TT
> with the
  <TT
CLASS="literal"
>-h</TT
> switch:
  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>Usage: php [options] [-f] &#60;file&#62; [args...]
       php [options] -r &#60;code&#62; [args...]
       php [options] [-- args...]
  -s               Display colour syntax highlighted source.
  -w               Display source with stripped comments and whitespace.
  -f &#60;file&#62;        Parse &#60;file&#62;.
  -v               Version number
  -c &#60;path&#62;|&#60;file&#62; Look for php.ini file in this directory
  -a               Run interactively
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -z &#60;file&#62;        Load Zend extension &#60;file&#62;.
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -i               PHP information
  -r &#60;code&#62;        Run PHP &#60;code&#62; without using script tags &#60;?..?&#62;
  -h               This help

  args...          Arguments passed to script. Use -- args when first argument 
                   starts with - or script is read from stdin</PRE
></TD
></TR
></TABLE
>
 </P
><P
>&#13;  The <TT
CLASS="literal"
>CLI SAPI</TT
> has three different ways of getting the
  <TT
CLASS="literal"
>PHP</TT
> code you want to execute:
  <P
></P
><OL
TYPE="1"
><LI
><P
>&#13;     Telling <TT
CLASS="literal"
>PHP</TT
> to execute a certain file.
    </P
><P
>&#13;     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>php my_script.php

php -f my_script.php</PRE
></TD
></TR
></TABLE
>
     Both ways (whether using the <TT
CLASS="literal"
>-f</TT
> switch or not) execute
     the file <TT
CLASS="filename"
>my_script.php</TT
>. You can choose any file to
     execute - your <TT
CLASS="literal"
>PHP</TT
> scripts do not have to end with the
     <TT
CLASS="filename"
>.php</TT
> extension but can have any name or extension
     you wish.
    </P
></LI
><LI
><P
>&#13;     Pass the <TT
CLASS="literal"
>PHP</TT
> code to execute directly on the command
     line.
    </P
><P
>&#13;     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>php -r 'print_r(get_defined_constants());'</PRE
></TD
></TR
></TABLE
>
     Special care has to be taken in regards of shell variable substitution and
     quoting usage.
    </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
      Read the example carefully, there are no beginning or ending tags! The
      <TT
CLASS="literal"
>-r</TT
> switch simply does not need them. Using them will
      lead to a parser error.
     </P
></BLOCKQUOTE
></DIV
></LI
><LI
><P
>&#13;     Provide the <TT
CLASS="literal"
>PHP</TT
> code to execute via standard input
     (<TT
CLASS="literal"
>stdin</TT
>).
    </P
><P
>&#13;     This gives the powerful ability to dynamically create
     <TT
CLASS="literal"
>PHP</TT
> code and feed it to the binary, as shown in this
     (fictional) example:
     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ some_application | some_filter | php | sort -u &#62;final_output.txt</PRE
></TD
></TR
></TABLE
>
    </P
></LI
></OL
>
  You cannot combine any of the three ways to execute code.
 </P
><P
>&#13;  Like every shell application, the <TT
CLASS="literal"
>PHP</TT
> binary
  accepts a number of arguments but your <TT
CLASS="literal"
>PHP</TT
> script can
  also receive arguments. The number of arguments which can be passed to your script
  is not limited by <TT
CLASS="literal"
>PHP</TT
> (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 <TT
CLASS="literal"
>$argv</TT
>. The zero index always contains the script
  name (which is <TT
CLASS="literal"
>-</TT
> in case the <TT
CLASS="literal"
>PHP</TT
> code
  is coming from either standard input or from the command line switch
  <TT
CLASS="literal"
>-r</TT
>). The second registered global variable is
  <TT
CLASS="literal"
>$argc</TT
> which contains the number of elements in the
  <TT
CLASS="literal"
>$argv</TT
> array (<SPAN
CLASS="strong"
><B
CLASS="emphasis"
>not</B
></SPAN
> the
  number of arguments passed to the script).
 </P
><P
>&#13;  As long as the arguments you want to pass to your script do not start with
  the <TT
CLASS="literal"
>-</TT
> character, there's nothing special to watch out
  for. Passing an argument to your script which starts with a
   <TT
CLASS="literal"
>-</TT
> will cause trouble because <TT
CLASS="literal"
>PHP</TT
>
   itself thinks it has to handle it. To prevent this, use the argument list
   separator <TT
CLASS="literal"
>--</TT
>. After this separator has been parsed by
   <TT
CLASS="literal"
>PHP</TT
>, every argument following it is passed
   untouched to your script.
 </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
># This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] &#60;file&#62; [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]=&#62;
  string(1) "-"
  [1]=&#62;
  string(2) "-h"
}</PRE
></TD
></TR
></TABLE
><P
>&#13;  However, there's another way of using <TT
CLASS="literal"
>PHP</TT
> for shell
  scripting. You can write a script where the first line starts with
  <TT
CLASS="literal"
>#!/usr/bin/php</TT
>. Following this you can place
  normal <TT
CLASS="literal"
>PHP</TT
> code included within the <TT
CLASS="literal"
>PHP</TT
>
  starting and end tags. Once you have set the execution attributes of the file
  appropriately (e.g. <TT
CLASS="literal"
>chmod +x test</TT
>) your script can be
  executed like a normal shell or perl script:
  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>#!/usr/bin/php
&#60;?php
    var_dump($argv);
?&#62;</PRE
></TD
></TR
></TABLE
>
  Assuming this file is named <TT
CLASS="filename"
>test</TT
> in the current
  directory, we can now do the following:
  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ chmod 755 test
$ ./test -h -- foo
array(4) {
  [0]=&#62;
  string(6) "./test"
  [1]=&#62;
  string(2) "-h"
  [2]=&#62;
  string(2) "--"
  [3]=&#62;
  string(3) "foo"
}</PRE
></TD
></TR
></TABLE
>
  As you see, in this case no care needs to be taken when passing parameters
  which start with <TT
CLASS="literal"
>-</TT
> to your script.
 </P
><P
>&#13;  <DIV
CLASS="table"
><A
NAME="AEN6680"
></A
><P
><B
>Table 23-3. Command line options</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Option</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-s</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Display colour syntax highlighted source.
       </P
>
       <P
>&#13;        This option uses the internal mechanism to parse the file and produces
        a <TT
CLASS="literal"
>HTML</TT
> highlighted version of it and writes it to
        standard output. Note that all it does it to generate a block of
        <TT
CLASS="literal"
>&#60;code&#62; [...] &#60;/code&#62;</TT
>
        <TT
CLASS="literal"
>HTML</TT
> tags, no <TT
CLASS="literal"
>HTML</TT
> headers.
       </P
>
       <DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
         This option does not work together with the <TT
CLASS="literal"
>-r</TT
>
         option.
        </P
></BLOCKQUOTE
></DIV
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-w</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Display source with stripped comments and whitespace.
       </P
>
       <DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
         This option does not work together with the <TT
CLASS="literal"
>-r</TT
>
         option.
        </P
></BLOCKQUOTE
></DIV
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-f</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Parses and executed the given filename to the <TT
CLASS="literal"
>-f</TT
>
        option. This switch is optional and can be left out. Only providing
        the filename to execute is sufficient.
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-v</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies</PRE
></TD
></TR
></TABLE
>
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-c</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        With this option one can either specify a directory where to look for
        <TT
CLASS="filename"
>php.ini</TT
> or you can specify a custom <TT
CLASS="literal"
>INI</TT
> file
        directly (which does not need to be named <TT
CLASS="filename"
>php.ini</TT
>), e.g.:
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php</PRE
></TD
></TR
></TABLE
>
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-a</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Runs PHP interactively.
        
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-d</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        This option allows you to set a custom value for any of the configuration
        directives allowed in <TT
CLASS="filename"
>php.ini</TT
>. The syntax is:
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>-d configuration_directive[=value]</PRE
></TD
></TR
></TABLE
>
       </P
>
       <P
>&#13;        Examples:
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
># 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"</PRE
></TD
></TR
></TABLE
>
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-e</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Generate extended information for debugger/profiler.
        
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-z</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        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 <TT
CLASS="filename"
>/etc/ld.so.conf</TT
> 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 <TT
CLASS="literal"
>PHP</TT
> only to try to
        load the extension relative to the current directory.
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-l</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        This option provides a convenient way to only perform a syntax check
        on the given <TT
CLASS="literal"
>PHP</TT
> code. On succes, the text
        <TT
CLASS="literal"
>No syntax errors detected in &#60;filename&#62;</TT
> is
        written to standard output and the shell return code is
        <TT
CLASS="literal"
>0</TT
>. On failure, the text <TT
CLASS="literal"
>Errors parsing
        &#60;filename&#62;</TT
> in addition to the internal parser error
        message is written to standard output and the shell return code is set
        to <TT
CLASS="literal"
>255</TT
>.
       </P
>
       <P
>&#13;        This option won't find fatal errors (like undefined functions). Use
        <TT
CLASS="literal"
>-f</TT
> if you would like to test for fatal errors too.
       </P
>
       <DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
         This option does not work together with the <TT
CLASS="literal"
>-r</TT
>
         option.
        </P
></BLOCKQUOTE
></DIV
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-m</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        Using this option, PHP prints out the built in (and loaded) PHP and
        Zend modules:
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]</PRE
></TD
></TR
></TABLE
>
       </P
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-i</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       This command line option calls <A
HREF="function.phpinfo.html"
><B
CLASS="function"
>phpinfo()</B
></A
>, and prints
       out the results. If <TT
CLASS="literal"
>PHP</TT
> is not working correctly, it is
       advisable to use <TT
CLASS="literal"
>php -i</TT
> and see whether any error
       messages are printed out before or in place of the information tables.
       Beware that the output is in <TT
CLASS="literal"
>HTML</TT
> and therefore
       quite huge.
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-r</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       <P
>&#13;        This option allows execution of <TT
CLASS="literal"
>PHP</TT
> right from
        within the command line. The <TT
CLASS="literal"
>PHP</TT
> start and end tags
        (<TT
CLASS="literal"
>&#60;?php</TT
> and <TT
CLASS="literal"
>?&#62;</TT
>) are
        <SPAN
CLASS="strong"
><B
CLASS="emphasis"
>not needed</B
></SPAN
> and will cause a parser
        error if present.
       </P
>
       <DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
         Care has to be taken when using this form of <TT
CLASS="literal"
>PHP</TT
>
         to not collide with command line variable substitution done by the
         shell.
        </P
><P
>&#13;         Example showing a parser error
         <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='</PRE
></TD
></TR
></TABLE
>
         The problem here is that the sh/bash performs variable substitution
         even when using double quotes <TT
CLASS="literal"
>"</TT
>. Since the
         variable <TT
CLASS="literal"
>$foo</TT
> is unlikely to be defined, it
         expands to nothing which results in the code passed to
         <TT
CLASS="literal"
>PHP</TT
> for execution actually reading:
         <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ php -r " = get_defined_constants();"</PRE
></TD
></TR
></TABLE
>
         The correct way would be to use single quotes <TT
CLASS="literal"
>'</TT
>.
         Variables in single-quoted strings are not expanded
         by sh/bash.
         <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=&#62;
  int(1)
  ["E_WARNING"]=&#62;
  int(2)
  ["E_PARSE"]=&#62;
  int(4)
  ["E_NOTICE"]=&#62;
  int(8)
  ["E_CORE_ERROR"]=&#62;
  [...]</PRE
></TD
></TR
></TABLE
>
         If you are using a shell different from sh/bash, you might experience
         further issues. Feel free to open a bug report or send a mail to
         phpdoc@lists.php.net.

         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. 
        </P
></BLOCKQUOTE
></DIV
>
       <DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
         <TT
CLASS="literal"
>-r</TT
> is available in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>CLI</I
></SPAN
>
         SAPI and not in the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>CGI</I
></SPAN
> SAPI.
        </P
></BLOCKQUOTE
></DIV
>
      </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>-h</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;       With this option, you can get information about the actual list of
       command line options and some one line descriptions about what they do.
      </TD
></TR
></TBODY
></TABLE
></DIV
>
 </P
><P
>&#13;  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 <TT
CLASS="literal"
>php.exe</TT
> with the double click option of the
  <TT
CLASS="literal"
>.php</TT
> 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.
 </P
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN6804"
></A
><P
><B
>Example 23-1. Script intended to be run from command line (script.php)</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>#!/usr/bin/php
&#60;?php

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

This is a command line PHP script with one option.

  Usage:
  &#60;?php echo $argv[0]; ?&#62; &#60;option&#62;

  &#60;option&#62; can be some word you would like
  to print out. With the --help, -help, -h,
  or -? options, you can get this help.

&#60;?php
} else {
    echo $argv[1];
}
?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
><P
>&#13;  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 HTTP header printouts. There are two
  variables you can use while writing command line applications with
  PHP: <TT
CLASS="varname"
>$argc</TT
> and <TT
CLASS="varname"
>$argv</TT
>. 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 (<TT
CLASS="varname"
>$argv[0]</TT
>).
 </P
><P
>&#13;  In the program above we checked if there are less or more than one
  arguments. Also if the argument was <TT
CLASS="literal"
>--help</TT
>,
  <TT
CLASS="literal"
>-help</TT
>, <TT
CLASS="literal"
>-h</TT
> or <TT
CLASS="literal"
>-?</TT
>,
  we printed out the help message, printing the script name dynamically.
  If we received some other argument we echoed that out.
 </P
><P
>&#13;  If you would like to run the above script on Unix, you need to
  make it executable, and simply call it as
  <TT
CLASS="literal"
>script.php echothis</TT
> or
  <TT
CLASS="literal"
>script.php -h</TT
>. On Windows, you can make a
  batch file for this task:
 </P
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN6819"
></A
><P
><B
>Example 23-2. Batch file to run a command line PHP script (script.bat)</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="winbat"
>@c:\php\cli\php.exe script.php %1 %2 %3 %4</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
><P
>&#13;  Assuming you named the above program
  <TT
CLASS="filename"
>script.php</TT
>, and you have your
  CLI <TT
CLASS="filename"
>php.exe</TT
> in
  <TT
CLASS="filename"
>c:\php\cli\php.exe</TT
> this batch file
  will run it for you with your added options:
  <TT
CLASS="literal"
>script.bat echothis</TT
> or
  <TT
CLASS="literal"
>script.bat -h</TT
>.
 </P
><P
>&#13;  See also the <A
HREF="ref.readline.html"
>Readline</A
>
  extension documentation for more functions you can use
  to enhance your command line applications in PHP.
 </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="features.safe-mode.functions.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="funcref.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Functions restricted/disabled by safe mode</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="features.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Function Reference</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>