mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
moved commandline to chapters/features
id correction in commandline.xml for chapters/features git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@81327 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Friedhelm Betz
parent
085892c1ba
commit
7585164af0
1 changed files with 287 additions and 0 deletions
287
features/commandline.xml
Normal file
287
features/commandline.xml
Normal file
|
|
@ -0,0 +1,287 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<!--
|
||||
TODO:
|
||||
|
||||
The command line options not in the
|
||||
list, but in the -h output below:
|
||||
|
||||
-e, -z
|
||||
|
||||
It would be best to document these, and
|
||||
collect more info about -c and -d!
|
||||
-->
|
||||
<chapter id="features.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 always 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:
|
||||
<screen>
|
||||
<![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
|
||||
]]>
|
||||
</screen>
|
||||
</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>-f</entry>
|
||||
<entry>
|
||||
Parse the file given, and search for syntactical and
|
||||
fatal errors. This option implies -q. Use for
|
||||
debugging purposes.
|
||||
</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 directory. 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
|
||||
&php.ini; 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
|
||||
&php.ini; settings in the
|
||||
time of running a script.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>-l</entry>
|
||||
<entry>
|
||||
Check the file given for syntax errors. This
|
||||
option implies -q. Use for debugging purposes.
|
||||
This option won't find fatal errors (like undefined
|
||||
functions). Use -f if you would like to test
|
||||
for fatal errors too.
|
||||
</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, printing 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 role="winbat">
|
||||
@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>
|
||||
<para>
|
||||
See also the <link linkend="ref.readline">Readline</link>
|
||||
extension documentation for more functions you can use
|
||||
to enhance your command line applications in PHP.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<!-- 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
|
||||
indent-tabs-mode:nil
|
||||
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