diff --git a/features/commandline.xml b/features/commandline.xml index 81ef4c2a2f..37564802e3 100644 --- a/features/commandline.xml +++ b/features/commandline.xml @@ -2,347 +2,261 @@ Using PHP from the command line - - PHP supports a CLI SAPI as of PHP 4.3.0. - The main focus of this SAPI is for developing shell - applications with PHP. There are quite a few differences between the - CLI SAPI and other - SAPIs which are explained in this chapter. It is worth - mentioning that CLI and CGI are different - SAPI's although they do share many of the same behaviors. - - - The CLI SAPI was released for the first time with - PHP 4.2.0, but was still experimental and had - to be explicitly enabled with when running - ./configure. Since PHP 4.3.0 the - CLI SAPI is no longer experimental and the option - is on by default. You may use - to disable it. - - - 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 make, both the CGI and CLI are built and - placed as sapi/cgi/php-cgi and sapi/cli/php - respectively, in your PHP source directory. You will note that both are - named php. What happens during make install depends on - your configure line. If a module SAPI is chosen during configure, such as apxs, or the - option is used, the CLI is copied to - {PREFIX}/bin/php during make install - otherwise the CGI is placed there. So, for example, if is in your configure line then the CLI is copied to - {PREFIX}/bin/php during make - install. If you want to override the installation of the CGI - binary, use make install-cli after make - install. Alternatively you can specify in your configure line. - - + Command line usage + + +
+ Introduction + - Because both and - are enabled by default, - simply having in your - configure line does not necessarily mean the CLI will be copied as - {PREFIX}/bin/php during make install. + PHP supports a &cli.sapi; as of PHP 4.3.0. The main focus of this + SAPI is for developing shell applications with PHP. There + are quite a few differences between the &cli.sapi; and other + SAPIs which are explained in this chapter. It is worth + mentioning that &cli; and CGI are different + SAPIs although they do share many of the same behaviors. - - - The Windows packages between PHP 4.2.0 and PHP 4.2.3 distributed the CLI as - php-cli.exe, living in the same folder as the CGI - php.exe. Starting with PHP 4.3.0 the Windows package - distributes the CLI as php.exe in a separate folder - named cli, so cli/php.exe - . Starting with PHP 5, the CLI is distributed in the main folder, - named php.exe. The CGI version is distributed as - php-cgi.exe. - - - As of PHP 5, a new php-win.exe file is distributed. - This is equal to the CLI version, except that php-win doesn't output - anything and thus provides no console (no "dos box" appears on the screen). - This behavior is similar to php-gtk. You should configure with - . - - - What SAPI do I have? + - From a shell, typing php -v will tell you - whether php is CGI or CLI. See also the function - php_sapi_name and the constant - PHP_SAPI. + The &cli.sapi; is enabled by default using + , but may be disabled using + the option when running + ./configure. - - + - A Unix manual page was added in PHP 4.3.2. You may - view this by typing man php in your shell environment. + 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 make, both the CGI + and &cli; are built and placed as sapi/cgi/php-cgi and + sapi/cli/php respectively, in your PHP source directory. + You will note that both are named php. What happens during + make install depends on your configure line. If a module + SAPI is chosen during configure, such as apxs, or the + option is used, the &cli; is + copied to {PREFIX}/bin/php during + make install otherwise the CGI is placed + there. So, for example, if is + in your configure line then the &cli; is copied to {PREFIX}/bin/php + during make install. If you want to override + the installation of the CGI binary, use make + install-cli after make install. Alternatively you + can specify in your configure + line. - - - Remarkable differences of the CLI SAPI compared to other - SAPIs: - - - - Unlike the CGI SAPI, no headers are written to the - output. - - - Though the CGI SAPI provides a way to suppress HTTP - headers, there's no equivalent switch to enable them in the CLI - SAPI. - - - 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. - - - It does not change the working directory to that of the script. - ( and switches kept for - compatibility) - - - Plain text error messages (no HTML formatting). - - - - - There are certain &php.ini; directives which are overridden by the CLI - SAPI because they do not make sense in shell environments: - - - - Overridden &php.ini; directives - - - - Directive - CLI SAPI default value - Comment - - - - - 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;. - - - - 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 defer or manipulate standard output. - - - - 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. - - - - register_argc_argv - &true; - - - Because this setting is &true; you will always have access to - argc (number of arguments passed to the - application) and argv (array of the actual - arguments) in the CLI SAPI. - - - As of PHP 4.3.0, the PHP variables $argc - and $argv are registered and filled in with the appropriate - values when using the CLI SAPI. Prior to this version, - the creation of these variables behaved as they do in - CGI and MODULE versions - which requires the PHP directive - register_globals to - be on. Regardless of version or register_globals - setting, you can always go through either - $_SERVER or - $HTTP_SERVER_VARS. Example: - $_SERVER['argv'] - - - - - output_buffering - &false; - + + + + Because both and + are enabled by default, + simply having in your + configure line does not necessarily mean the &cli; will be copied as + {PREFIX}/bin/php during make install. + + + + + As of PHP 5, the &cli; binary is distributed in the main folder as + php.exe on Windows. The CGI version is + distributed as php-cgi.exe. Additionally, a + php-win.exe is distributed if PHP is configured using + . This does the same as + the &cli; version, except that it doesn't output anything and thus provides + no console. + + + + What SAPI do I have? + + From a shell, typing php -v will tell you + whether php is CGI or &cli;. See + also the function php_sapi_name and the constant + PHP_SAPI. + + + + + + A Unix manual page is available by typing man + php in your shell environment. + + + + + + +
+ Differences to other <acronym>SAPI</acronym>s + + + Remarkable differences of the &cli; SAPI compared to other + SAPIs: + + + + Unlike the CGI SAPI, no headers are + written to the output. + + + Though the CGI SAPI provides a way + to suppress HTTP headers, there's no equivalent switch to enable them in + the &cli.sapi;. + + + &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. + + + It does not change the working directory to that of the script. + ( and switches kept for + compatibility) + + + Plain text error messages (no HTML formatting). + + + + + + There are certain &php.ini; directives which are overridden by the + &cli.sapi; because they do not make sense in shell environments: + + +
+ Overridden &php.ini; directives + + + + Directive + &cli; SAPI default value + Comment + + + + + 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;. + + + + 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 + defer or manipulate standard output. + + + + 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. + + + + register_argc_argv + &true; + - Altough the INI setting is hardcoded to &false; the - Output buffering functions - are available. + Because this setting is &true; you will always have access to + argc (number of arguments passed to the + application) and argv (array of the actual + arguments) in the &cli; SAPI. - - - - max_input_time - &false; - - The PHP CLI doesn't not support GET, POST or file uploads. + 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'] - - - - -
- - - - 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). + + + + output_buffering + &false; + + + Altough the &php.ini; setting is hardcoded to &false; the + Output buffering functions + are available. + + + + + max_input_time + &false; + + + The PHP &cli; doesn't not support GET, POST or file uploads. + + + + + + - - + + + 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). + + + + + It is recommended to set + ignore_user_abort for + command line scripts. See ignore_user_abort for + more info. + + + + + - It is recommended to set - ignore_user_abort for - command line scripts. See ignore_user_abort for - more info. + To ease working in the shell environment, a number of constants are + defined for I/O streams + . - - - - - To ease working in the shell environment, the following constants - are defined: - - CLI specific Constants - - - - Constant - Description - - - - - STDIN - - An already opened stream to stdin. This saves - opening it with - - -]]> - - If you want to read single line from stdin, you can - use - - -]]> - - - - - STDOUT - - An already opened stream to stdout. This saves - opening it with - - -]]> - - - - - STDERR - - - An already opened stream to stderr. - This saves opening it with - - -]]> - - - - - - -
- - - Given the above, you don't need to open e.g. a stream for - stderr yourself but simply use the constant instead of - the stream resource: - - - - You do not need to explicitly close these streams, as they are closed - automatically by PHP when your script ends. - - + + + - These constants are not available in case of reading PHP script from - stdin. + The &cli.sapi; does not change the + current directory to the directory of the executed script! - - - - - The CLI SAPI does not change the current directory to the directory - of the executed script! - - - - Example showing the difference to the CGI SAPI: - - + + + Example showing the difference to the CGI + SAPI: + + ]]> - - - When using the CGI version, the output is: - - + + + When using the CGI version, the output is: + + - - - This clearly shows that PHP changes its current - directory to the one of the executed script. - - - Using the CLI SAPI yields: - - + + + This clearly shows that PHP changes its current directory to the one of + the executed script. + + + Using the &cli.sapi; yields: + + - - - This allows greater flexibility when writing shell tools in PHP. - - - - - The CGI SAPI supports this CLI SAPI - behaviour by means of the switch when run from the - command line. - - - - - - - The list of command line options provided by the PHP - binary can be queried anytime by running PHP with the - switch: - + + + This allows greater flexibility when writing shell tools in PHP. + + + + + The CGI SAPI supports this + &cli.sapi; behaviour by means of the switch when run + from the command line. + + + + + +
+ + + +
+ Command line options + Options + + + The list of command line options provided by the PHP binary can be queried + anytime by running PHP with the switch: + [--] [args...] php [options] -r [--] [args...] @@ -425,303 +346,141 @@ Usage: php [options] [-f] [--] [args...] --re Show information about extension . --ri Show configuration for extension . ]]> - - - - The CLI SAPI has three different ways of getting the - PHP code you want to execute: - - - - Telling PHP to execute a certain file. - - - - - - - - Both ways (whether using the switch or not) execute - the file my_script.php. You can choose any file to - execute - your PHP scripts do not have to end with the - .php extension but can have any name or extension - you wish. - - - - If you need to pass arguments to your scripts you need to pass - -- as the first argument when using the - switch. - - - - - - Pass the PHP code to execute directly on the command - line. - - - - - - - - Special care has to be taken in regards of shell variable substitution and - quoting usage. - - - - 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. - - - - - - Provide the PHP code to execute via standard input - (stdin). - - - This gives the powerful ability to dynamically create - PHP code and feed it to the binary, as shown in this - (fictional) example: - - - -final_output.txt -]]> - - - - - You cannot combine any of the three ways to execute code. - - - 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 zero index always contains the script - name (which is - in case the PHP code - is coming from either standard input or from the command line switch - ). The second registered global variable is - $argc which 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 - 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. - - - - [args...] -[...] - -# This will pass the '-h' argument to your script and prevent PHP from showing it's usage -$ php -r 'var_dump($argv);' -- -h -array(2) { - [0]=> - string(1) "-" - [1]=> - string(2) "-h" -} -]]> - - - - However, there's another way of using PHP for shell - scripting. You can write a script where the first line starts with - #!/usr/bin/php. 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: - - - Execute PHP script as shell script - - -]]> - - - Assuming this file is named test in the current - directory, we can now do the following: + - - - string(6) "./test" - [1]=> - string(2) "-h" - [2]=> - string(2) "--" - [3]=> - string(3) "foo" -} -]]> - - - - As you see, in this case no care needs to be taken when passing parameters - which start with - to your script. - - - - Command line options - - - - Option - Long Option - Description - - - - - -a - --interactive - - - Runs PHP interactively. If you compile PHP with the Readline extension (which is not - available on Windows), you'll have a nice shell, including a - completion feature (e.g. you can start typing a variable name, hit the - TAB key and PHP completes its name) and a typing history that can be - accessed using the arrow keys. The history is saved in the - ~/.php_history file. - - + + +
+ Command line options + + + + Option + Long Option + Description + + + + + -a + --interactive + - Files included through auto_prepend_file and auto_append_file are parsed in - this mode but with some restrictions - e.g. functions have to be - defined before called. + Runs PHP interactively. If you compile PHP with the Readline extension (which is not + available on Windows), you'll have a nice shell, including a + completion feature (e.g. you can start typing a variable name, hit the + TAB key and PHP completes its name) and a typing history that can be + accessed using the arrow keys. The history is saved in the + ~/.php_history file. - - + + + Files included through auto_prepend_file and auto_append_file are parsed in + this mode but with some restrictions - e.g. functions have to be + defined before called. + + + + + Autoloading is not + available if using PHP in &cli; interactive mode. + + + + + + -b + --bindpath + - Autoloading is not available if using PHP in CLI - interactive mode. + Bind Path for external FASTCGI Server mode (CGI + only). - - - - - -b - --bindpath - - - Bind Path for external FASTCGI Server mode (CGI only). - - - - - -C - --no-chdir - - - Do not chdir to the script's directory (CGI only). - - - - - -q - --no-header - - - Quiet-mode. Suppress HTTP header output (CGI only). - - - - - -T - --timing - - - Measure execution time of script repeated count - times (CGI only). - - - - - -c - --php-ini - - - This option can either specify a directory where to look for - &php.ini; or specify a custom INI file - (which does not need to be named &php.ini;), e.g.: - - - + + + + -C + --no-chdir + + + Do not chdir to the script's directory (CGI only). + + + + + -q + --no-header + + + Quiet-mode. Suppress HTTP header output + (CGI only). + + + + + -T + --timing + + + Measure execution time of script repeated count + times (CGI only). + + + + + -c + --php-ini + + + This option can either specify a directory where to look for + &php.ini; or specify a custom INI file + (which does not need to be named &php.ini;), e.g.: + + + - - - - If you don't specify this option, file is searched in - default locations. - - - - - -n - --no-php-ini - - - Ignore &php.ini; at all. This switch is available since PHP 4.3.0. - - - - - -d - --define - - - This option allows you to set a custom value for any of the configuration - directives allowed in &php.ini;. The syntax is: - - - - - + + - Examples (lines are wrapped for layout reasons): + If you don't specify this option, file is searched in + default locations. - + + + + -n + --no-php-ini + + + Ignore &php.ini; at all. + + + + + -d + --define + + + This option allows you to set a custom value for any of the configuration + directives allowed in &php.ini;. The syntax is: + + + + + + + Examples (lines are wrapped for layout reasons): + + - - - - - - -e - --profile-info - - - Activate the extended information mode, to be used by a - debugger/profiler. - - - - - -f - --file - - - Parses and executes the given filename to the - option. This switch is optional and can be left out. Only providing - the filename to execute is sufficient. - - + + + + + + -e + --profile-info + - To pass arguments to scripts the first argument needs to be - --, otherwise PHP will interperate them as PHP - options. + Activate the extended information mode, to be used by a + debugger/profiler. - - - - - -h and -? - --help and --usage - - With this option, you can get information about the actual list of - command line options and some one line descriptions about what they do. - - - - -i - --info - - This command line option calls phpinfo, and prints - out the results. If PHP is not working correctly, it is - advisable to use php -i and see whether any error - messages are printed out before or in place of the information tables. - Beware that when using the CGI mode the output is in HTML - and therefore quite huge. - - - - -l - --syntax-check - - - This option provides a convenient way to only perform a syntax check - on the given PHP code. On success, the text - No syntax errors detected in <filename> is - written to standard output and the shell return code is - 0. On failure, the text Errors parsing - <filename> in addition to the internal parser error - message is written to standard output and the shell return code is set - to -1. - - - This option won't find fatal errors (like undefined functions). Use - if you would like to test for fatal errors too. - - + + + + -f + --file + - This option does not work together with the - option. + Parses and executes the given filename to the + option. This switch is optional and can be left out. Only providing + the filename to execute is sufficient. - - - - - -m - --modules - - + + + To pass arguments to scripts the first argument needs to be + --, otherwise PHP will interperate them as PHP + options. + + + + + + -h and -? + --help and --usage + + With this option, you can get information about the actual list of + command line options and some one line descriptions about what they do. + + + + -i + --info + + This command line option calls phpinfo, and prints + out the results. If PHP is not working correctly, it is + advisable to use php -i and see whether any error + messages are printed out before or in place of the information tables. + Beware that when using the CGI mode the output is in + HTML and therefore quite huge. + + + + -l + --syntax-check + - Using this option, PHP prints out the built in (and loaded) PHP and - Zend modules: + This option provides a convenient way to only perform a syntax check + on the given PHP code. On success, the text + No syntax errors detected in <filename> is + written to standard output and the shell return code is + 0. On failure, the text Errors parsing + <filename> in addition to the internal parser error + message is written to standard output and the shell return code is set + to -1. - + + This option won't find fatal errors (like undefined functions). Use + if you would like to test for fatal errors too. + + + + This option does not work together with the + option. + + + + + + -m + --modules + + + + Using this option, PHP prints out the built in (and loaded) PHP and + Zend modules: + + - - - - - - -r - --run - - - This option allows execution of PHP right from - within the command line. The PHP start and end tags - (<?php and ?>) are - not needed and will cause a parser - error if present. - - + + + + + + -r + --run + - Care has to be taken when using this form of PHP - to not collide with command line variable substitution done by the - shell. + This option allows execution of PHP right from + within the command line. The PHP start and end tags + (<?php and ?>) are + not needed and will cause a parser + error if present. - + - Example showing a parser error + Care has to be taken when using this form of PHP + to not collide with command line variable substitution done by the + shell. - + + + Example showing a parser error + + - - - - The problem here is that the sh/bash performs variable substitution - even when using double quotes ". Since the - variable $foo is unlikely to be defined, it - expands to nothing which results in the code passed to - PHP for execution actually reading: - - - + + + + The problem here is that the sh/bash performs variable substitution + even when using double quotes ". Since the + variable $foo is unlikely to be defined, it + expands to nothing which results in the code passed to + PHP for execution actually reading: + + + - - - The correct way would be to use single quotes '. - Variables in single-quoted strings are not expanded - by sh/bash. - - + + + The correct way would be to use single quotes '. + Variables in single-quoted strings are not expanded + by sh/bash. + + [...] ]]> - - + + + + If you are using a shell different from sh/bash, you might experience + further issues. Feel free to open a bug report at + &url.php.bugs;. + 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. + + + + + is available in the &cli.sapi; and not in the + CGI SAPI. + + + + + This option is meant for a very basic stuff. Thus some configuration + directives (e.g. auto_prepend_file and auto_append_file) are ignored + in this mode. + + + + + + -B + --process-begin + - If you are using a shell different from sh/bash, you might experience - further issues. Feel free to open a bug report at - &url.php.bugs;. - 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. + PHP code to execute before processing stdin. Added in PHP 5. - - + + + + -R + --process-code + - is available in the CLI - SAPI and not in the CGI SAPI. + PHP code to execute for every input line. Added in PHP 5. - - - This option is meant for a very basic stuff. Thus some configuration - directives (e.g. auto_prepend_file and auto_append_file) are ignored - in this mode. + There are two special variables available in this mode: + $argn and $argi. + $argn will contain the line PHP is processing at + that moment, while $argi will contain the line + number. - - - - - -B - --process-begin - - - PHP code to execute before processing stdin. Added in PHP 5. - - - - - -R - --process-code - - - PHP code to execute for every input line. Added in PHP 5. - - - There are two special variables available in this mode: - $argn and $argi. - $argn will contain the line PHP is processing at - that moment, while $argi will contain the line - number. - - - - - -F - --process-file - - - PHP file to execute for every input line. Added in PHP 5. - - - - - -E - --process-end - - - PHP code to execute after processing the input. Added in PHP 5. - - - Using the <option>-B</option>, <option>-R</option> and - <option>-E</option> options to count the number of lines of a - project. - - + + + + -F + --process-file + + + PHP file to execute for every input line. Added in PHP 5. + + + + + -E + --process-end + + + PHP code to execute after processing the input. Added in PHP 5. + + + Using the <option>-B</option>, <option>-R</option> and + <option>-E</option> options to count the number of lines of a + project. + + - - - - - - -s - --syntax-highlight and --syntax-highlighting - - - Display colour syntax highlighted source. - - - 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 - <code> [...] </code> - HTML tags, no HTML headers. - - + + + + + + -s + --syntax-highlight and --syntax-highlighting + - This option does not work together with the - option. + Display colour syntax highlighted source. - - - - - -v - --version - - - Writes the PHP, PHP SAPI, and Zend version to standard output, e.g. + 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 + <code> [...] </code> + HTML tags, no HTML headers. - + + + This option does not work together with the + option. + + + + + + -v + --version + + + + Writes the PHP, PHP SAPI, and Zend version to + standard output, e.g. + + - - - - - - -w - --strip - - - Display source with stripped comments and whitespace. - - + + + + + + -w + --strip + - This option does not work together with the - option. + Display source with stripped comments and whitespace. - - - - - -z - --zend-extension - - - 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 /etc/ld.so.conf 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. - - - - - - --ini - - - Shows configuration file names and scanned directories. Available as - of PHP 5.2.3. - - <literal>--ini</literal> example - + + + This option does not work together with the + option. + + + + + + -z + --zend-extension + + + 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 /etc/ld.so.conf 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. + + + + + + --ini + + + Shows configuration file names and scanned directories. Available as + of PHP 5.2.3. + + <literal>--ini</literal> example + - - - - - - - --rf - --rfunction - - - Shows information about the given function or class method (e.g. - number and name of the parameters). Available as of PHP 5.1.2. - - - This option is only available if PHP was compiled with - Reflection support. - - - - basic <literal>--rf</literal> usage - + + + + + + + --rf + --rfunction + + + Shows information about the given function or class method (e.g. + number and name of the parameters). Available as of PHP 5.1.2. + + + This option is only available if PHP was compiled with + Reflection support. + + + + basic <literal>--rf</literal> usage + public function var_dump ] { @@ -1112,27 +875,27 @@ Function [ public function var_dump ] { } } ]]> - - - - - - - --rc - --rclass - - - Show information about the given class (list of constants, properties - and methods). Available as of PHP 5.1.2. - - - This option is only available if PHP was compiled with - Reflection support. - - - - <literal>--rc</literal> example - + + + + + + + --rc + --rclass + + + Show information about the given class (list of constants, properties + and methods). Available as of PHP 5.1.2. + + + This option is only available if PHP was compiled with + Reflection support. + + + + <literal>--rc</literal> example + class Directory ] { @@ -1161,27 +924,27 @@ Class [ class Directory ] { } } ]]> - - - - - - - --re - --rextension - - - Show information about the given extension (list of &php.ini; options, - defined functions, constants and classes). Available as of PHP 5.1.2. - - - This option is only available if PHP was compiled with - Reflection support. - - - - <literal>--re</literal> example - + + + + + + + --re + --rextension + + + Show information about the given extension (list of &php.ini; options, + defined functions, constants and classes). Available as of PHP 5.1.2. + + + This option is only available if PHP was compiled with + Reflection support. + + + + <literal>--re</literal> example + extension #19 json version 1.2.1 ] { @@ -1194,25 +957,25 @@ Extension [ extension #19 json version 1.2.1 ] { } } ]]> - - - - - - - --ri - --rextinfo - - - Shows 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. - - - - <literal>--ri</literal> example - + + + + + + + --ri + --rextinfo + + + Shows 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. + + + + <literal>--ri</literal> example + 10.776699 => 10.776699 date.sunset_zenith => 90.583333 => 90.583333 date.sunrise_zenith => 90.583333 => 90.583333 ]]> - - - - - - - -
- - The long options (i.e. --no-chdir) are available since PHP 4.3.3. - - - - - Options -rBRFEH, --ini and - --r[fcei] are available only in CLI. + + + + + + + + - + + + + Options -rBRFEH, --ini and + --r[fcei] are available only in &cli;. + + +
+ + + +
+ Executing PHP files + Usage + + + The &cli.sapi; has three different ways of getting the PHP code you want to + execute: + + + + Telling PHP to execute a certain file. + + + + - 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. - - +$ 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. + + + + If you need to pass arguments to your scripts you need to pass + -- as the first argument when using the + switch. + + + + + + Pass the PHP code to execute directly on the command line. + + + + + + + + Special care has to be taken in regards of shell variable substitution and + quoting usage. + + + + 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. + + + + + + Provide the PHP code to execute via standard input + (stdin). + + + This gives the powerful ability to dynamically create PHP code and feed it + to the binary, as shown in this (fictional) example: + + + + final_output.txt +]]> + + + + + You cannot combine any of the three ways to execute code. + + + + 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 zero index always contains the + script name (which is - in case the PHP codeis coming from + either standard input or from the command line switch ). + The second registered global variable is $argc which + 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 + 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. + + + + + [args...] +[...] + +# This will pass the '-h' argument to your script and prevent PHP from showing it's usage +$ php -r 'var_dump($argv);' -- -h +array(2) { + [0]=> + string(1) "-" + [1]=> + string(2) "-h" +} +]]> + + + + + 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: + + - Script intended to be run from command line (script.php) + Execute PHP script as shell script +]]> + + + Assuming this file is named test in the current + directory, we can now do the following: + + + + string(6) "./test" + [1]=> + string(2) "-h" + [2]=> + string(2) "--" + [3]=> + string(3) "foo" +} +]]> + + + + + As you see, in this case no care needs to be taken when passing parameters + which start with - to your script. + + + + 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. + + + + + Script intended to be run from command line (script.php) + + @@ -1287,64 +1224,172 @@ 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]). - - - 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. - - - 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: - - - - Batch file to run a command line PHP script (script.bat) - + + + + + + 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]). + + + + 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. + + + + 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: + + + + + Batch file to run a command line PHP script (script.bat) + + + + + + + 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: + script.bat echothis or script.bat -h. + + + + See also the Readline extension + documentation for more functions you can use to enhance your command line + applications in PHP. + + + + If you are on Windows, PHP can be configured to run without the need to + supply the C:\php\php.exe or the .php + extension, as descibed in Command + Line PHP on Microsoft Windows. + +
+ + + +
+ Input/output streams + I/O streams + + + The &cli.sapi; defines a few constants for I/O streams to make programming + for the command line a bit easier. + + + + + CLI specific Constants + + + + Constant + Description + + + + + STDIN + + An already opened stream to stdin. This saves + opening it with + + +]]> + + If you want to read single line from stdin, you can + use + + +]]> + + + + + STDOUT + + An already opened stream to stdout. This saves + opening it with + + +]]> + + + + + STDERR + + + An already opened stream to stderr. + This saves opening it with + + +]]> + + + + + + +
+ + + + Given the above, you don't need to open e.g. a stream for + stderr yourself but simply use the constant instead of + the stream resource: + + - - - - 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: - script.bat echothis or - script.bat -h. - - - See also the Readline - extension documentation for more functions you can use - to enhance your command line applications in PHP. - - - If you are on Windows, PHP can be configured to run without the need to - supply the C:\php\php.exe or the .php - extension, as descibed in Command - Line PHP on Microsoft Windows. - + You do not need to explicitly close these streams, as they are closed + automatically by PHP when your script ends. + + + + + These constants are not available in case of reading PHP script from + stdin. + + +
+ +