From 63d77489f7f2cbddd4d0067fb3e43b9170c896b0 Mon Sep 17 00:00:00 2001 From: Markus Fischer Date: Fri, 10 May 2002 21:11:05 +0000 Subject: [PATCH] - Initial cli documentation. # Now let's get this into the right place git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@81707 c90b9560-bf6c-de11-be94-00142212c4b1 --- features/commandline.xml | 659 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 636 insertions(+), 23 deletions(-) diff --git a/features/commandline.xml b/features/commandline.xml index 4dec681a80..9b26779ba6 100644 --- a/features/commandline.xml +++ b/features/commandline.xml @@ -1,18 +1,632 @@ - - + Using PHP from the command line + + + Since version 4.3, PHP supports a new + SAPI type (Server Application Programming Interface) + named CLI which means Command Line + Interface. As the name implies, this SAPI type + main focus is on developing shell (or desktop as well) applications with + PHP. There are quite some differences between the + CLI SAPI and other SAPIs which are + further explained throughout this chapter. + + + The CLI SAPI was released for the first time with + PHP 4.2.0, but was still experimental back then and had + to be explicitely enabled with --enable-cli when running + ./configure. Since PHP 4.3.0 the + CLI SAPI is no longer experimental and is therefore + always built and installed as the + php (called php.exe on Windows) + binary. + + + Remarkable differences of the CLI SAPI compared to other + SAPIs: + + + + Unlikely the CGI SAPI, no headers are written to the + output. + + + Though the CGI SAPI provies a way to suppress HTTP + headers, there's not equivalent switch to enable them in the CLI + SAPI. + + + + + The are certain &php.ini; directives which are overriden by the CLI + SAPI because the do not make sense in shell environments: + + Overriden &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 + immidiately written to the output and not cached in any buffer. + + + + 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 executed + within splits of a seconds, shell application tend to have a much + longer execution time. + + + + register_argc_argv + &true; + + The global PHP variables $argc + (number of arguments passed to the application) and + $argv (array of the actual arguments) are always + registered and filled in with the appropriate values when using the + CLI SAPI. + + + + +
+ + + + This directives cannot be initialzied 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). + + + + + + The CLI SAPI does not change the current directory to the directory + of the executed script ! + + + Example showing the difference to the CGI SAPI: + + +]]> + + + + 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 allows for greater flexibility when writing shell tools in + PHP. + + + + The CGI SAPI supports the CLI SAPI + behaviour by means of the -C switch when ran from the + command line. + + + + + + + The list of command line options provided by the PHP + binary can be queryied anytime by running PHP with the + -h switch: + + [args...] + php [options] -r [args...] + php [options] [-- args...] + -s Display colour syntax highlighted source. + -w Display source with stripped comments and whitespace. + -f Parse . + -v Version number + -c | 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 Load Zend extension . + -l Syntax check only (lint) + -m Show compiled in modules + -i PHP information + -r Run PHP 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 +]]> + + + + 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 (using the -f switch or not) execute the + given 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 give them any name or extension + you want them to have. + + + + + 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, thera are no beginning or end tags! The + -r 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 not only the PHP binary + accepts a number of arguments but also your PHP script + can receive them. The number of arguments which can be passed to your script + is not limited by PHP (the shell has a certain size limit + in numbers 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 + -r). 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 whatch out + for. Passing an argument to your script which starts with a + - will cause trouble because PHP + thinks it has to handle it. To prevent this use the argument list separator + --. After argument has been parsed by + PHP, every argument following it is passed + untoched/unparsed 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" +} +]]> + + + But, there's another way of using PHP for shell + scripting. You can write a script whose first line starts with + #!/usr/bin/php and then following the normal + PHP code included within the PHP + starting and end tags and set the execution attributes of the file + appropriately. This way it can be executed like a normal shell or perl + 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 no care has to be taken when passing parameters to your script + which start with -. + + + + Command line options + + + + Option + Description + + + + + -s + + + 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. + + + + This option does not work together with the -r + option. + + + + + + -w + + + Display source with stripped comments and whitespace. + + + + This option does not work together with the -r + option. + + + + + + -f + + + Parses and executed the given filename to the -f + option. This switch is optional and can be left out. Only providing + the filename to execute is sufficient. + + + + + -v + + + Writes the PHP and Zend version to standard output, e.g. + +$ php -v +PHP 4.3.0-dev (cli) +Zend Engine v1.2.1, Copyright (c) 1998-2002 Zend Technologies + + + + + + -c + + + With this option one can either specify a directory where to look for + &php.ini; or you can specify a custom INI file + directly (which does not need to be named &php.ini;), e.g.: + +$ php -c /custom/directory/ my_script.php + +$ php -c /custom/directory/custom-file.ini my_script.php + + + + + + -a + + + Runs PHP interactively. + + + + + + -d + + + This option allows to set a custom value for any of the configuration + directives allowed in &php.ini;. The syntax is: + + + + + + Examples: + + + + + + + + -e + + + Generate extended information for debugger/profiler. + + + + + + -z + + + 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 Unix + 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. + + + + + -l + + + This option provides a convenient way to only perform a syntax check + on the given PHP code. On succes, 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 255. + + + This option won't find fatal errors (like undefined functions). Use + -f if you would like to test for fatal errors too. + + + + This option does not work together with the -r + option. + + + + + + -m + + + Using this option, PHP prints out the built in (and loaded) PHP and + Zend modules: + +$ php -m +[PHP Modules] +xml +tokenizer +standard +session +posix +pcre +overload +mysql +mbstring +ctype + +[Zend Modules] + + + + + + + -i + + This command line option calls phpinfo, and prints + out the results. If PHP is not working well, it is + advisable to make a php -i and see if any error + messages are printed out before or in place of the information tables. + Beware that the output is in HTML and therefore + quite huge. + + + + -r + + + 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 + errors. + + + + 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 shell performs variable substritution + even when using double quotes ". Since the + variable $foo is unlikely to be defined, it + expands to nothing which results in being the code passed to + PHP for executin in fact reads: + + + + The correct way would be to use single quotes '. + The shell doesn't expand variables in strings quoted with single + quotes: + + + int(1) + ["E_WARNING"]=> + int(2) + ["E_PARSE"]=> + int(4) + ["E_NOTICE"]=> + int(8) + ["E_CORE_ERROR"]=> + [...] +]]> + + One still can easily run intro troubles when trying to get shell + variables into the code or using backslashes for escaping. You've + been warned. + + + + + + -h + + With this option, you can get information about the actual list of + command line options and some one line descriptions about what they do. + + + + +
+ + + + - 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 -q 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 + 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)