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