mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Adding long avaited "Using PHP from commandline" appendix.
It was written by me, with the command line option meanings guessed from usage. There may be some errors, so if someone have the time to read through, it would be good. IMHO it turned out to be a good one, with instructions about writing command line scripts, and running them on Unix and Windows. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@59920 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gabor Hojtsy
parent
12b99e586e
commit
643e51181d
1 changed files with 263 additions and 0 deletions
263
appendices/commandline.xml
Normal file
263
appendices/commandline.xml
Normal file
|
|
@ -0,0 +1,263 @@
|
|||
<?xml encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<!--
|
||||
TODO:
|
||||
|
||||
The command line options not in the
|
||||
list, but in the -h output below:
|
||||
|
||||
-f, -e, -z, -l
|
||||
|
||||
It would be best to document these, and
|
||||
collect more info about -c and -d!
|
||||
-->
|
||||
<appendix id="commandline">
|
||||
<title>Using PHP from the command line</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Note, that you can allways 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 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:
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]}
|
||||
-q Quiet-mode. Suppress HTTP Header output.
|
||||
-s Display colour syntax highlighted source.
|
||||
-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
|
||||
-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
|
||||
-h This help
|
||||
]]>
|
||||
</programlisting>
|
||||
</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>-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 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.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>-c</entry>
|
||||
<entry>
|
||||
Using this option, you can specify an alternative
|
||||
<filename>php.ini</filename> 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
|
||||
<filename>php.ini</filename> settings in the
|
||||
time of running a script.
|
||||
</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
|
||||
|
||||
if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
|
||||
?>
|
||||
|
||||
This is a command line PHP script with one option.
|
||||
|
||||
Usage:
|
||||
<?php echo $argv[0]; ?> <option>
|
||||
|
||||
<option> can be some word you would like
|
||||
to print out. With the --help, -help, -h,
|
||||
or -? options, you can get this help.
|
||||
|
||||
<?php
|
||||
} else {
|
||||
echo $argv[1];
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</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, printng 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>
|
||||
@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>
|
||||
</appendix>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
Loading…
Reference in a new issue