From 6173c244f9ac3bdfccc1d62925e6dc8dc6ffb7c4 Mon Sep 17 00:00:00 2001
From: Marcus Boerger <helly@php.net>
Date: Sun, 23 Jun 2002 01:26:02 +0000
Subject: [PATCH] explain cli and difference to cgi
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@86452 c90b9560-bf6c-de11-be94-00142212c4b1
---
appendices/commandline.xml | 725 ++++++++++++++++++++++++++-----------
1 file changed, 518 insertions(+), 207 deletions(-)
diff --git a/appendices/commandline.xml b/appendices/commandline.xml
index 6436e9785e..80fa58758a 100644
--- a/appendices/commandline.xml
+++ b/appendices/commandline.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
<!--
TODO:
@@ -19,29 +19,40 @@
can also be handy, if you would like to use PHP for a
different purpose than web scripting.
</para>
- <para>
- Note, that you can always direct the output of the PHP
- executable to an external file with the > character,
- so <literal>php -q test.php > test.html</literal> will
- print out the output of <filename>test.php</filename>
- without HTTP headers to the <filename>test.html</filename>
- file in the same directory.
+ <para>
+ There are two commandline versions of PHP. First you can
+ use the CGI version of PHP as a commandline interpreter and
+ since version 4.2 of PHP you can use the CLI version where
+ CLI stands for Command Line Interface. As the name suggests
+ the CLI version has some modifications which allow easier
+ use on the commandline.
</para>
- <para>
- You can only use these command line options if you have
- the PHP executable. If you built the server module
- version, and you have no CGI version available on your
- machine, than you have no chance to use these options.
- For Windows users both the PHP executable and the server
- modules are in the binary package, the executable is
- named <filename>php.exe</filename>.
- </para>
- <para>
- This list of command line options is consistent with PHP 4.0.6.
- You can get the actual list and some one line descriptions
- with the <literal>-h</literal> option. The output of
- <literal>php -h</literal> should be something like this:
- <screen>
+ <section id="commandline.cgi">
+ <title>The CGI version</title>
+ <para>
+ Note, that you can always direct the output of the PHP
+ executable to an external file with the > character,
+ so <literal>php -q test.php > test.html</literal> will
+ print out the output of <filename>test.php</filename>
+ without HTTP headers to the <filename>test.html</filename>
+ file in the same directory.
+ </para>
+ <para>
+ You can only use these command line options if you have
+ the PHP executable. If you built the server module
+ version, and you have no CGI version available on your
+ machine, than you have no chance to use these options.
+ For Windows users both the PHP executable and the server
+ modules are in the binary package, the executable is
+ named <filename>php.exe</filename>.
+ </para>
+ <para>
+ This list of command line options is consistent with
+ the CGI version of PHP 4.0.6.
+ You can get the actual list and some one line descriptions
+ with the <literal>-h</literal> option. The output of
+ <literal>php -h</literal> should be something like this:
+ <screen>
<![CDATA[
Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]}
-q Quiet-mode. Suppress HTTP Header output.
@@ -49,7 +60,7 @@ Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]}
-f <file> Parse <file>. Implies `-q'
-v Version number
-C Do not chdir to the script's directory
- -c <path> Look for php.ini file in this directory
+ -c <path> Look for &php.ini; file in this directory
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-z <file> Load Zend extension <file>.
@@ -58,143 +69,145 @@ Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]}
-i PHP information
-h This help
]]>
- </screen>
- </para>
- <para>
- Here we list some of the most important command line options
- with detailed explanations.
- </para>
- <para>
- <table>
- <title>Command line options</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>-q</entry>
- <entry>
- Suppress HTTP headers output. Normally PHP prints out
- HTTP headers for the calling program (ie. webserver)
- to hand on to the browser. When writing command line
- applications these headers are useless.
- </entry>
- </row>
- <row>
- <entry>-s</entry>
- <entry>
- Display the color highlighted source of the file
- given with its name. This is the same as if you were
- printing out the source using the
- <function>highlight_file</function> function in
- a PHP script.
- </entry>
- </row>
- <row>
- <entry>-f</entry>
- <entry>
- Parse the file given, and search for syntactical and
- fatal errors. This option implies -q. Use for
- debugging purposes.
- </entry>
- </row>
- <row>
- <entry>-v</entry>
- <entry>
- By calling PHP with this option, you can ask
- it to print out its version number, ie: 4.0.6.
- </entry>
- </row>
- <row>
- <entry>-C</entry>
- <entry>
- Normally PHP changes the working directory to the
- running scripts directory. This makes it possible
- for example, to open files in the same directory,
- with only specifying the name of the file. If you
- would like to disable this directory change, use
- this option.
- </entry>
- </row>
- <row>
- <entry>-c</entry>
- <entry>
- Using this option, you can specify an alternative
- &php.ini; path, so PHP will
- search your configurations file in this path
- instead of the default one.
- </entry>
- </row>
- <row>
- <entry>-d</entry>
- <entry>
- With this option, you can set individual
- &php.ini; settings in the
- time of running a script.
- </entry>
- </row>
- <row>
- <entry>-l</entry>
- <entry>
- Check the file given for syntax errors. This
- option implies -q. Use for debugging purposes.
- This option won't find fatal errors (like undefined
- functions). Use -f if you would like to test
- for fatal errors too.
- </entry>
- </row>
- <row>
- <entry>-m</entry>
- <entry>
- Using this option, PHP prints out the built in
- (and loaded) PHP and Zend modules, the PHP
- and Zend version numbers, and a short Zend
- copyright notice.
- </entry>
- </row>
- <row>
- <entry>-i</entry>
- <entry>
- This command line option calls
- <function>phpinfo</function>, and prints
- out the results. If PHP is not working well,
- it is advisable to make a <literal>php -i</literal>
- and see if any error messages are printed out
- before or in place of the information tables.
- </entry>
- </row>
- <row>
- <entry>-h</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>
- </tbody>
- </tgroup>
- </table>
- </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
- <literal>php.exe -q</literal> 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>
- <example>
- <title>Script intended to be run from command line (script.php)</title>
- <programlisting role="php">
+ </screen>
+ </para>
+ <para>
+ Here we list some of the most important command line options
+ with detailed explanations.
+ </para>
+ <para>
+ <table>
+ <title>Command line options</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-q</entry>
+ <entry>
+ Suppress HTTP headers output. Normally PHP prints out
+ HTTP headers for the calling program (ie. webserver)
+ to hand on to the browser. When writing command line
+ applications these headers are useless.
+ </entry>
+ </row>
+ <row>
+ <entry>-s</entry>
+ <entry>
+ Display the color highlighted source of the file
+ given with its name. This is the same as if you were
+ printing out the source using the
+ <function>highlight_file</function> function in
+ a PHP script.
+ </entry>
+ </row>
+ <row>
+ <entry>-f</entry>
+ <entry>
+ Parse the file given, and search for syntactical and
+ fatal errors. This option implies -q. Use for
+ debugging purposes.
+ </entry>
+ </row>
+ <row>
+ <entry>-v</entry>
+ <entry>
+ By calling PHP with this option, you can ask
+ it to print out its version number, ie: 4.0.6.
+ </entry>
+ </row>
+ <row>
+ <entry>-C</entry>
+ <entry>
+ Normally PHP changes the working directory to the
+ running scripts directory. This makes it possible
+ for example, to open files in the same directory,
+ with only specifying the name of the file. If you
+ would like to disable this directory change, use
+ this option.
+ </entry>
+ </row>
+ <row>
+ <entry>-c</entry>
+ <entry>
+ Using this option, you can specify an alternative
+ &php.ini; path, so PHP will
+ search your configurations file in this path
+ instead of the default one.
+ It is possible to specify a filename to force loading
+ settings from a specific file.
+ </entry>
+ </row>
+ <row>
+ <entry>-d</entry>
+ <entry>
+ With this option, you can set individual
+ &php.ini; settings in the
+ time of running a script.
+ </entry>
+ </row>
+ <row>
+ <entry>-l</entry>
+ <entry>
+ Check the file given for syntax errors. This
+ option implies -q. Use for debugging purposes.
+ This option won't find fatal errors (like undefined
+ functions). Use -f if you would like to test
+ for fatal errors too.
+ </entry>
+ </row>
+ <row>
+ <entry>-m</entry>
+ <entry>
+ Using this option, PHP prints out the built in
+ (and loaded) PHP and Zend modules, the PHP
+ and Zend version numbers, and a short Zend
+ copyright notice.
+ </entry>
+ </row>
+ <row>
+ <entry>-i</entry>
+ <entry>
+ This command line option calls
+ <function>phpinfo</function>, and prints
+ out the results. If PHP is not working well,
+ it is advisable to make a <literal>php -i</literal>
+ and see if any error messages are printed out
+ before or in place of the information tables.
+ </entry>
+ </row>
+ <row>
+ <entry>-h</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>
+ </tbody>
+ </tgroup>
+ </table>
+ </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
+ <literal>php.exe -q</literal> 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>
+ <example>
+ <title>Script intended to be run from command line (script.php)</title>
+ <programlisting role="php">
<![CDATA[
#!/usr/bin/php -q
<?php
@@ -217,52 +230,350 @@ This is a command line PHP script with one option.
}
?>
]]>
- </programlisting>
- </example>
- <para>
- In the script above, we used the special first line to indicate,
- that this file should be run by PHP and should not print out HTTP
- headers. 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 <literal>--help</literal>,
- <literal>-help</literal>, <literal>-h</literal> or <literal>-?</literal>,
- 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
- <literal>script.php echothis</literal> or
- <literal>script.php -h</literal>. On Windows, you can make a
- batch file for this task:
- </para>
- <example>
- <title>Batch file to run a command line PHP script (script.bat)</title>
- <programlisting role="winbat">
-@c:\php\php.exe -q script.php %1 %2 %3 %4
- </programlisting>
- </example>
- <para>
- Assuming, you named the above program as
- <filename>script.php</filename>, and you have your
- <filename>php.exe</filename> in
- <filename>c:\php\php.exe</filename> this batch file
- will run it for you with your added options:
- <literal>script.bat echothis</literal> or
- <literal>script.bat -h</literal>.
- </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>
+ </programlisting>
+ </example>
+ <para>
+ In the script above, we used the special first line to indicate,
+ that this file should be run by PHP and should not print out HTTP
+ headers. 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 <literal>--help</literal>,
+ <literal>-help</literal>, <literal>-h</literal> or <literal>-?</literal>,
+ 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
+ <literal>script.php echothis</literal> or
+ <literal>script.php -h</literal>. On Windows, you can make a
+ batch file for this task:
+ </para>
+ <example>
+ <title>Batch file to run a command line PHP script (script.bat)</title>
+ <programlisting role="winbat">
+ @c:\php\php.exe -q script.php %1 %2 %3 %4
+ </programlisting>
+ </example>
+ <para>
+ Assuming, you named the above program as
+ <filename>script.php</filename>, and you have your
+ <filename>php.exe</filename> in
+ <filename>c:\php\php.exe</filename> this batch file
+ will run it for you with your added options:
+ <literal>script.bat echothis</literal> or
+ <literal>script.bat -h</literal>.
+ </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>
+ </section>
+ <section id="commandline.cli">
+ <title>The CLI version</title>
+ <para>
+ The following list explains the differences of the
+ CLI version.
+ </para>
+ <itemizedlist>
+ <listitem><simpara>
+ CLI is started up in quiet mode by default. But <literal>-q</literal>
+ switch is kept for compatibility so that you can use older CGI scripts.
+ </simpara></listitem>
+ <listitem><simpara>
+ It does not change the working directory to that of the script.
+ (<literal>-C</literal> switch kept for compatibility)
+ </simpara></listitem>
+ <listitem><simpara>
+ Plain text error messages.
+ </simpara></listitem>
+ <listitem><simpara>
+ $argc and $argv are registered irrespective of register_globals.
+ </simpara></listitem>
+ <listitem><simpara>
+ implicit_flush is always set on.
+ </simpara></listitem>
+ <listitem><simpara>
+ Additional <literal>-r</literal> option which allows execution of PHP
+ code directly from the command line (see below).
+ </simpara></listitem>
+ <listitem><simpara>
+ max_execution_time is set to unlimited, overriding &php.ini; setting.
+ </simpara></listitem>
+ <listitem><simpara>
+ <literal>--</literal> can be used to explicitly mark the end of CLI
+ options and therefore allowing options to the script that could be
+ program options (see below).
+ </simpara></listitem>
+ </itemizedlist>
+ <para>
+ This list of command line options is consistent with
+ the CLI version of PHP 4.2.0
+ You can get the actual list and some one line descriptions
+ with the <literal>-h</literal> option. The output of
+ <literal>php -h</literal> should be something like this:
+ <screen>
+<![CDATA[
+Usage: php [options] [-f] <file> [args...]
+ php [options] -r <code> [args...]
+ php [options] [-- args...]
+ -s Display colour syntax highlighted source.
+ -w Display source with stripped comments and whitespace.
+ -f <file> Parse <file>.
+ -v Version number
+ -c <path> 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 <file> Load Zend extension <file>.
+ -l Syntax check only (lint)
+ -m Show compiled in modules
+ -i PHP information
+ -r <code> Run PHP <code> without using script tags <?..?>
+ -h This help
+
+ args... Arguments passed to script. Use -- args when first argument
+ starts with - or script is read from stdin
+]]>
+ </screen>
+ </para>
+ <para>
+ Here we list some of the most important command line options
+ with detailed explanations.
+ </para>
+ <para>
+ <table>
+ <title>Command line options</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-q</entry>
+ <entry>
+ Kept for compatibility to CGI version.
+ </entry>
+ </row>
+ <row>
+ <entry>-s</entry>
+ <entry>
+ Display the color highlighted source of the file
+ given with its name. This is the same as if you were
+ printing out the source using the
+ <function>highlight_file</function> function in
+ a PHP script.
+ </entry>
+ </row>
+ <row>
+ <entry>-f</entry>
+ <entry>
+ Parse the file given, and search for syntactical and
+ fatal errors. This option implies -q. Use for
+ debugging purposes.
+ </entry>
+ </row>
+ <row>
+ <entry>-v</entry>
+ <entry>
+ By calling PHP with this option, you can ask
+ it to print out its version number, ie: 4.0.6.
+ </entry>
+ </row>
+ <row>
+ <entry>-C</entry>
+ <entry>
+ Kept for compatibility to CGI version.
+ </entry>
+ </row>
+ <row>
+ <entry>-c</entry>
+ <entry>
+ Using this option, you can specify an alternative
+ &php.ini; path, so PHP will
+ search your configurations file in this path
+ instead of the default one.
+ It is possible to specify a filename to force loading
+ settings from a specific file.
+ </entry>
+ </row>
+ <row>
+ <entry>-d</entry>
+ <entry>
+ With this option, you can set individual
+ &php.ini; settings in the
+ time of running a script.
+ </entry>
+ </row>
+ <row>
+ <entry>-l</entry>
+ <entry>
+ Check the file given for syntax errors. This
+ option implies -q. Use for debugging purposes.
+ This option won't find fatal errors (like undefined
+ functions). Use -f if you would like to test
+ for fatal errors too.
+ </entry>
+ </row>
+ <row>
+ <entry>-m</entry>
+ <entry>
+ Using this option, PHP prints out the built in
+ (and loaded) PHP and Zend modules, the PHP
+ and Zend version numbers, and a short Zend
+ copyright notice.
+ </entry>
+ </row>
+ <row>
+ <entry>-i</entry>
+ <entry>
+ This command line option calls
+ <function>phpinfo</function>, and prints
+ out the results. If PHP is not working well,
+ it is advisable to make a <literal>php -i</literal>
+ and see if any error messages are printed out
+ before or in place of the information tables.
+ </entry>
+ </row>
+ <row>
+ <entry>-h</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>-r</entry>
+ <entry>
+ Execute code direct from commandline (see below).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ <example>
+ <title>Hello World 1</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -r 'echo "Hello World!\n";'
+Hello World!
+]]>
+ </programlisting>
+ </example>
+ The single quotations enclose the command to be executed. In the
+ example that is an invocation of echo with one string parameter.
+ As you can see it is better to use single quotes for the command
+ enclosing because it allows usage of <literal>\n</literal> in the
+ code.
+ </para>
+ <para>
+ <example>
+ <title>Hello World 2</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -r 'echo "Hello ";echo "World!\n";'
+Hello World!
+]]>
+ </programlisting>
+ </example>
+ Here we use more than one command separated by <literal>;</literal>.
+ </para>
+ <para>
+ The global variable $argc and $argv are allways available. The
+ first index of $argv 0 indicates either the executed script or
+ - if CLI is executed with -r or with code from standars in.
+ <example>
+ <title>Filename of -r</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -r 'echo $argv[0];'
+-
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>Hello World 3</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -r 'echo $argv[1];' 'Hello World!'
+Hello World!
+]]>
+ </programlisting>
+ </example>
+ This example passes exact one parameter to the executed command.
+ </para>
+ <para>
+ When you possibly have parameters starting with a minus sign you
+ must use <literal>--</literal> to explicitly mark the end of
+ CLI parameterlist. A special case is using CLI with standard in
+ which requires the usage of -- allways.
+ <example>
+ <title>Parameter that could be a CLI option</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -r 'echo "$argv[1]\n";' -- -i
+-i
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ The next example shows that arguments can be passed
+ to scripts executed from standard in or redirection.
+ <example>
+ <title>hello.php script used for next example</title>
+ <programlisting role="php">
+<![CDATA[
+<?
+array_splice($argv, 0, 1);
+echo join(' ', $argv);
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Hello World 4</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -- Hello World! < hello.php
+Hello World!
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ You can execute scripts that have names which match
+ option names like <literal>-i</literal>. This is because
+ the option -f must be followed by a scriptname. The following
+ example assumes that you rename <literal>hello.php</literal>
+ to <literal>-i</literal>.
+ <example>
+ <title>Executing scripts with option names</title>
+ <programlisting role="php">
+<![CDATA[
+#!/usr/bin/php -f -i -- Hello World!
+Hello World!
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
</appendix>
<!-- Keep this comment at the end of the file