diff --git a/appendices/commandline.xml b/appendices/commandline.xml new file mode 100644 index 0000000000..4c1f7bceab --- /dev/null +++ b/appendices/commandline.xml @@ -0,0 +1,263 @@ + + + + + Using PHP from the command line + + The command line options of the PHP executable are useful + if you would like to debug or test your PHP setup, but they + can also be handy, if you would like to use PHP for a + different purpose than web scripting. + + + Note, that you can allways direct the output of the PHP + executable to an external file with the > character, + so php -q test.php > test.html will + print out the output of test.php + without HTTP headers to the test.html + file in the same directory. + + + 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 php.exe. + + + 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 -h option. The output of + php -h should be something like this: + +] | { [args...]} + -q Quiet-mode. Suppress HTTP Header output. + -s Display colour syntax highlighted source. + -f Parse . Implies `-q' + -v Version number + -C Do not chdir to the script's directory + -c 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 Load Zend extension . + -l Syntax check only (lint) + -m Show compiled in modules + -i PHP information + -h This help +]]> + + + + Here we list some of the most important command line options + with detailed explanations. + + + + Command line options + + + + Option + Description + + + + + -q + + 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. + + + + -s + + 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 + highlight_file function in + a PHP script. + + + + -v + + By calling PHP with this option, you can ask + it to print out its version number, ie: 4.0.6. + + + + -C + + Normally PHP changes the working directory to the + running scripts direcrory. 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. + + + + -c + + 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. + + + + -d + + With this option, you can set individual + php.ini settings in the + time of running a script. + + + + -m + + 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. + + + + -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. + + + + -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. + + + Script intended to be run from command line (script.php) + + + +This is a command line PHP script with one option. + + Usage: + + + + 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: $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 --help, + -help, -h or -?, + we printed out the help message, printng 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) + +@c:\php\php.exe -q script.php %1 %2 %3 %4 + + + + Assuming, you named the above program as + script.php, and you have your + 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. + + + +