diff --git a/features/commandline.xml b/features/commandline.xml index df55c2f8fe..f004286fbb 100644 --- a/features/commandline.xml +++ b/features/commandline.xml @@ -78,7 +78,7 @@ A Unix manual page is available by typing man - php in your shell environment. + php in the shell environment. @@ -105,7 +105,7 @@ &cli; is started up in quiet mode by default, though the and switches are kept for compatibility so - that you can use older CGI scripts. + that it is possible to use older CGI scripts. It does not change the working directory to that of the script. @@ -138,19 +138,20 @@ html_errors &false; - It can be quite hard to read the error message in your shell when - it's cluttered with all those meaningless HTML - tags, therefore this directive defaults to &false;. + Defaults to &false;, as it can be quite hard to read error messages + in the shell enviroment when they are cluttered up with uninterpreted + HTML tags. implicit_flush &true; - It is desired that any output coming from print, - echo and friends is immediately written to the - output and not cached in any buffer. You still can use - output buffering if you want to + In a shell environment, it is usually desirable for output, such as + from print, echo and + friends, to be displayed immediately, and not held in a buffer. + Nonetheless, it is still possible to use + output buffering to defer or manipulate standard output. @@ -158,10 +159,9 @@ max_execution_time 0 (unlimited) - 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. + PHP in a shell environment tends to be used for a much more diverse + range of purposes than typical Web-based scripts, and as these can + be very long-running, the maximum execution time is set to unlimited. @@ -169,17 +169,18 @@ &true; - Because this setting is &true; you will always have access to - argc (number of arguments passed to the + Setting this to &true; means that scripts executed via the + &cli; SAPI always have access to + argc (number of arguments passed to the application) and argv (array of the actual - arguments) in the &cli; SAPI. + arguments). The PHP variables $argc - and $argv are registered and filled in with the appropriate - values when using the &cli; SAPI. You can also go - through $_SERVER or. Example: - $_SERVER['argv'] + and $argv are automatically set to the appropriate + values when using the &cli; SAPI. These values can + also be found in the $_SERVER array, for example: + $_SERVER['argv']. @@ -188,7 +189,7 @@ &false; - Although the &php.ini; setting is hardcoded to &false; the + Although the &php.ini; setting is hardcoded to &false;, the Output buffering functions are available. @@ -210,11 +211,11 @@ 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. register_argc_argv). + configuration file &php.ini; or a custom one (if specified). This + limitation is because the values are applied after all configuration + files have been parsed. However, their values can be changed + during runtime (although this is not sensible for all of them, + such as register_argc_argv). @@ -222,7 +223,7 @@ It is recommended to set ignore_user_abort for command line scripts. See ignore_user_abort for - more info. + more information. @@ -238,7 +239,7 @@ The &cli.sapi; does not change the - current directory to the directory of the executed script! + current directory to the directory of the executed script. @@ -305,7 +306,7 @@ $ php -f another_directory/test.php <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: + at any time by running PHP with the <option>-h</option> switch: <screen> <![CDATA[ Usage: php [options] [-f] <file> [--] [args...] @@ -367,7 +368,7 @@ Usage: php [options] [-f] <file> [--] [args...] <entry>--interactive</entry> <entry> <para> - Runs PHP interactively. For more information, see the <link + Run PHP interactively. For more information, see the <link linkend="features.commandline.interactive">Interactive shell</link> section. </para> @@ -417,8 +418,8 @@ Usage: php [options] [-f] <file> [--] [args...] <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 + Specifies either a directory in which to look for + &php.ini;, or a custom <literal>INI</literal> file (which does not need to be named &php.ini;), e.g.: </para> <para><informalexample> @@ -431,7 +432,7 @@ $ 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 + If this option is not specified, &php.ini; is searched for in the <link linkend="configuration.file">default locations</link>. </para> </entry> @@ -441,7 +442,7 @@ $ php -c /custom/directory/custom-file.ini my_script.php <entry>--no-php-ini</entry> <entry> <para> - Ignore &php.ini; at all. + Ignore &php.ini; completely. </para> </entry> </row> @@ -450,7 +451,7 @@ $ php -c /custom/directory/custom-file.ini my_script.php <entry>--define</entry> <entry> <para> - This option allows you to set a custom value for any of the configuration + Set a custom value for any of the configuration directives allowed in &php.ini;. The syntax is: <screen> <![CDATA[ @@ -499,14 +500,14 @@ string(15) "doesntmakesense" <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 + Parse and execute the specified file. The + <option>-f</option> is optional and may be omitted - providing just the filename to execute is sufficient. </para> <note> <para> - To pass arguments to scripts the first argument needs to be - <literal>--</literal>, otherwise PHP will interperate them as PHP + To pass arguments to a script, the first argument must be + <literal>--</literal>, otherwise PHP will interpret them as PHP options. </para> </note> @@ -516,20 +517,20 @@ string(15) "doesntmakesense" <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. + Output a list of + command line options with one line descriptions of what they do. </entry> </row> <row> <entry>-i</entry> <entry>--info</entry> <entry> - 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 + Calls <function>phpinfo</function>, and prints out the results. + If PHP is not working correctly, it is advisable to use the command + <command>php -i</command> and see whether any error messages are printed out before or in place of the information tables. Beware that when using the <acronym>CGI</acronym> mode the output is in - <acronym>HTML</acronym> and therefore quite huge. + <acronym>HTML</acronym> and therefore very large. </entry> </row> <row> @@ -537,7 +538,7 @@ string(15) "doesntmakesense" <entry>--syntax-check</entry> <entry> <para> - This option provides a convenient way to only perform a syntax check + Provides a convenient way to perform only a syntax check on the given PHP code. On success, the text <literal>No syntax errors detected in <filename></literal> is written to standard output and the shell return code is @@ -548,7 +549,7 @@ string(15) "doesntmakesense" </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. + the <option>-f</option> to test for fatal errors too. </para> <note> <para> @@ -590,16 +591,15 @@ ctype <entry>--run</entry> <entry> <para> - This option allows execution of PHP right from - within the command line. The PHP start and end tags - (<literal><?php</literal> and <literal>?></literal>) are - <emphasis role="strong">not needed</emphasis> and will cause a parser - error if present. + Allows execution of PHP included directly on the command line. + The PHP start and end tags (<literal><?php</literal> and + <literal>?></literal>) are <emphasis role="strong">not + needed</emphasis> and will cause a parse 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 + Care must be taken when using this form of PHP not + to collide with command line variable substitution done by the shell. </para> <example> @@ -614,7 +614,7 @@ 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 + The problem here is that sh/bash performs variable substitution even when using double quotes <literal>"</literal>. Since the variable <varname>$foo</varname> is unlikely to be defined, it expands to nothing which results in the code passed to @@ -654,24 +654,24 @@ array(370) { </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 + If using a shell other than sh/bash, further issues might be + experienced - if appropriate, a bug report should be opened at <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>. - 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. + It is still easy to run into trouble when trying to use variables + (shell or PHP) in commnad-line code, or using backslashes for + escaping, so take great care when doing so. You have been warned! </para> </note> <note> <para> - <option>-r</option> is available in the &cli.sapi; and not in the + <option>-r</option> is available in the &cli.sapi;, but not in the <emphasis>CGI</emphasis> <acronym>SAPI</acronym>. </para> </note> <note> <para> - This option is meant for a very basic stuff. Thus some configuration - directives (e.g. <link + This option is only intended for very basic code, so some + configuration directives (such as <link linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link linkend="ini.auto-append-file">auto_append_file</link>) are ignored in this mode. @@ -742,9 +742,9 @@ Total Lines: 37328 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 + This option uses the internal mechanism to parse the file and writes + an HTML highlighted version of it to + standard output. Note that all it does is generate a block of <literal><code> [...] </code></literal> HTML tags, no HTML headers. </para> @@ -766,7 +766,7 @@ Total Lines: 37328 <screen> <![CDATA[ $ php -v -PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07) +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 ]]> @@ -779,7 +779,7 @@ Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies <entry>--strip</entry> <entry> <para> - Display source with stripped comments and whitespace. + Display source with comments and whitespace stripped. </para> <note> <para> @@ -796,11 +796,11 @@ Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies <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. + (usually <filename>/etc/ld.so.conf</filename> on Linux systems, for + example). Passing a filename with an absolute path will + not use the system's library search path. A relative filename including + directory information will tell PHP to try + loading the extension relative to the current directory. </para> </entry> </row> @@ -809,7 +809,7 @@ Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies <entry>--ini</entry> <entry> <para> - Shows configuration file names and scanned directories. Available as + Show configuration file names and scanned directories. Available as of PHP 5.2.3. <example> <title><literal>--ini</literal> example @@ -831,7 +831,7 @@ Additional .ini files parsed: (none) --rfunction - Shows information about the given function or class method (e.g. + Show information about the given function or class method (e.g. number and name of the parameters). Available as of PHP 5.1.2. @@ -944,7 +944,7 @@ Extension [ extension #19 json version 1.2.1 ] { --rzendextension - Shows the configuration information for the given Zend extension (the + Show the configuration information for the given Zend extension (the same information that is returned by phpinfo). Available as of PHP 5.4.0. @@ -955,10 +955,10 @@ Extension [ extension #19 json version 1.2.1 ] { --rextinfo - Shows the configuration information for the given extension (the same + Show the configuration information for the given extension (the same information that is returned by phpinfo). Available as of PHP 5.2.2. The core configuration information - are available using "main" as extension name. + is available using "main" as extension name. @@ -1006,12 +1006,12 @@ date.sunrise_zenith => 90.583333 => 90.583333 Usage - The &cli.sapi; has three different ways of getting the PHP code you want to - execute: + There are three different ways of supplying the &cli.sapi; with PHP code + to be executed: - Telling PHP to execute a certain file. + Tell PHP to execute a certain file. @@ -1024,16 +1024,14 @@ $ php -f my_script.php Both ways (whether using the switch or not) execute - the file my_script.php. You can choose any file to - execute, and your PHP scripts do not have to end with the - .php extension but can have any name or extension - you wish. + the file my_script.php. Note that there is no + restriction on which files can be executed; in particular, the filename + is not required have a .php extension. - If you need to pass arguments to your scripts you need to pass - -- as the first argument when using the - switch. + If arguments need to be passed to the script when using + , the first argument must be --. @@ -1049,14 +1047,14 @@ $ php -r 'print_r(get_defined_constants());' - Special care has to be taken in regards of shell variable substitution and - quoting usage. + Special care has to be taken with regard to shell variable substitution and + usage of quotes. - Read the example carefully, there are no beginning or ending tags! The - switch simply does not need them. Using them will - lead to a parser error. + Read the example carefully: there are no beginning or ending tags! The + switch simply does not need them, and using them will + lead to a parse error. @@ -1066,7 +1064,7 @@ $ php -r 'print_r(get_defined_constants());' (stdin). - This gives the powerful ability to dynamically create PHP code and feed it + This gives the powerful ability to create PHP code dynamically and feed it to the binary, as shown in this (fictional) example: @@ -1082,33 +1080,34 @@ $ some_application | some_filter | php | sort -u > final_output.txt - 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 $argv. The first index (zero) always contains the - name of the script as called from the command line. Note that, if the code is - executed in-line using the command line switch , the value of - $argv[0] will be simply a dash (-). The - same is true if the code is executed via a pipe from STDIN. + As with every shell application, the PHP binary accepts a number of + arguments; however, the PHP script can also receive further arguments. The + number of arguments that can be passed to your script is not limited by PHP + (and although the shell has a limit to the number of characters which can be + passed, this is not in general likely to be hit). The arguments passed to + the script are available in the global array $argv. The + first index (zero) always contains the name of the script as called from the + command line. Note that, if the code is executed in-line using the command + line switch , the value of $argv[0] + will be just a dash (-). The same is true if the code is + executed via a pipe from STDIN. - The second registered global variable is $argc which + A second global variable, $argc, contains the number of elements in the $argv array (not the number of arguments passed to the script). - As long as the arguments you want to pass to your script do not start with + As long as the arguments to be passed to the script do not start with the - character, there's nothing special to watch out for. - Passing an argument to your script which starts with a - - will cause trouble because PHP itself thinks it has to handle it. To prevent - this, use the argument list separator --. After this - separator has been parsed by PHP, every argument following it is passed - untouched to your script. + Passing an argument to the script which starts with a - + will cause trouble because the PHP interpreter thinks it has to handle it + itself, even before executing the script. To prevent this, use the argument + list separator --. After this separator has been parsed by + PHP, every following argument is passed untouched to the script. @@ -1119,7 +1118,7 @@ $ php -r 'var_dump($argv);' -h Usage: php [options] [-f] [args...] [...] -# This will pass the '-h' argument to your script and prevent PHP from showing it's usage +# This will pass the '-h' argument to the script and prevent PHP from showing its usage $ php -r 'var_dump($argv);' -- -h array(2) { [0]=> @@ -1132,13 +1131,13 @@ array(2) { - 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 - #!/usr/bin/php (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. chmod +x test) - your script can be executed like a normal shell or perl script: + However, on Unix systems there's another way of using PHP for shell + scripting: make the first line of the script start with + #!/usr/bin/php (or whatever the path to your PHP &cli; + binary is if different). The rest of the file should contain normal PHP code + within the usual PHP starting and end tags. Once the execution attributes of + the file are set appropriately (e.g. chmod +x test), + the script can be executed like any other shell or perl script: @@ -1153,7 +1152,7 @@ var_dump($argv); Assuming this file is named test in the current - directory, we can now do the following: + directory, it is now possible to do the following: - As you see, in this case no care needs to be taken when passing parameters - which start with - to your script. + As can be seen, in this case no special care needs to be taken when passing parameters + starting with -. - 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 php.exe with the double click option of the - .php 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. + The PHP executable can be used to run PHP scripts absolutely independent of + the web server. On Unix systems, the special #! (or + "shebang") first line should be added to PHP scripts so that the system can + automatically tell which program should run the script. On Windows platforms, + it's possible to associate php.exe with the double + click option of the .php extension, or a batch file can + be created to run scripts through PHP. The special shebang first line for + Unix does no harm on Windows (as it's formatted as a PHP comment), so cross + platform programs can be written by including it. A simple example of + writing a command line PHP program is shown below. @@ -1222,29 +1221,26 @@ This is a command line PHP script with one option. - 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: - $argc and $argv. 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 ($argv[0]). + The script above includes the Unix shebang first line to indicate that this + file should be run by PHP. We are working with a &cli; version here, so + no HTTP headers will be output. - In the program above we checked if there are less or more than one arguments. - Also if the argument was , , - or , we printed out the help message, - printing the script name dynamically. If we received some other argument we - echoed that out. + The program first checks that there is the required one argument (in + addition to the script name, which is also counted). If not, or if the + argument was , , + or , the help message is printed out, + using $argv[0] to dynamically print the script name as + typed on the command line. Otherwise, the argument is echoed out exactly as + received. - If you would like to run the above script on Unix, you need to make it - executable, and simply call it as script.php echothis or - script.php -h. On Windows, you can make a batch file for - this task: + To run the above script on Unix, it must be made + executable, and called simply as script.php echothis or + script.php -h. On Windows, a batch file similar to the + following can be created for this task: @@ -1260,20 +1256,20 @@ This is a command line PHP script with one option. - Assuming you named the above program script.php, and you - have your &cli; php.exe in C:\php\php.exe - this batch file will run it for you with your added options: + Assuming the above program is named script.php, and the + &cli; php.exe is in C:\php\php.exe, + this batch file will run it, passing on all appended options: script.bat echothis or script.bat -h. See also the Readline extension - documentation for more functions you can use to enhance your command line + documentation for more functions which can be used to enhance command line applications in PHP. - If you are on Windows, PHP can be configured to run without the need to + On Windows, PHP can be configured to run without the need to supply the C:\php\php.exe or the .php extension, as described in Command Line PHP on Microsoft Windows. @@ -1399,7 +1395,7 @@ php -r 'fwrite(STDERR, "stderr\n");' - Executing code using the interactive shell + Executing code using the interactive shell var_dump(addtwo(2)); int(4) -php > +php > ]]> @@ -1447,8 +1443,8 @@ php > strpt[TAB]ime( ]]> - It is also possible doing completion on things that have been defined - during the interactive shell session: + Completion will also work for names that have been defined + during the current interactive shell session: $foo[TAB]ThisIsAReallyLongVariableName - The interactive shell stores your history and can be accessed using the up + The interactive shell stores your history which can be accessed using the up and down keys. The history is saved in the ~/.php_history file. As of PHP 5.4.0, the &cli.sapi; provides - two new &php.ini; settings: cli.pager and + the &php.ini; settings cli.pager and cli.prompt. The cli.pager setting allows an external program (such as less) to act as a pager for the output instead of being displayed directly on the @@ -1475,7 +1471,7 @@ php > $foo[TAB]ThisIsAReallyLongVariableName - In PHP 5.4.0 it was also made possible setting + In PHP 5.4.0 it was also made possible to set &php.ini; settings in the interactive shell using a shorthand notation.