philip Wed Dec 25 04:14:55 2002 EDT
Modified files:
/phpdoc/en/features commandline.xml
Log:
Began the process of documenting CLI and CGI as of PHP 4.3.0. Includes
various tidbits of information including how to compile, what the binaries
may be named, etc. Also updated the examples to reflect current behavior.
Index: phpdoc/en/features/commandline.xml
diff -u phpdoc/en/features/commandline.xml:1.12 phpdoc/en/features/commandline.xml:1.13
--- phpdoc/en/features/commandline.xml:1.12 Thu Nov 14 06:22:58 2002
+++ phpdoc/en/features/commandline.xml Wed Dec 25 04:14:54 2002
@@ -1,28 +1,70 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
+<!-- $Revision: 1.13 $ -->
<chapter id="features.commandline">
<title>Using PHP from the command line</title>
<!-- NEW DOCUMENTATION STARTS -->
<para>
- As of version 4.3, <literal>PHP</literal> supports a new
+ As of version 4.3.0, <literal>PHP</literal> supports a new
<literal>SAPI</literal> type (Server Application Programming Interface)
named <literal>CLI</literal> which means <emphasis>Command Line
Interface</emphasis>. As the name implies, this <literal>SAPI</literal> type
main focus is on developing shell (or desktop as well) applications with
- <literal>PHP</literal>. There are quite some differences between the
+ <literal>PHP</literal>. There are quite a few differences between the
<literal>CLI SAPI</literal> and other <literal>SAPI</literal>s which are
- further explained throughout this chapter.
+ further explained throughout this chapter. It's worth mentioning
+ that <literal>CLI</literal> and <literal>CGI</literal> are different
+ SAPI's although they do share many of the same behaviors.
</para>
<para>
The <literal>CLI SAPI</literal> was released for the first time with
- <literal>PHP 4.2.0</literal>, but was still experimental back then and had
+ <literal>PHP 4.2.0</literal>, but was still experimental and had
to be explicitely enabled with <literal>--enable-cli</literal> when running
- <literal>./configure</literal>. Since <literal>PHP 4.3.0</literal> the
- <literal>CLI SAPI</literal> is no longer experimental and is therefore
- <emphasis role="strong">always</emphasis> built and installed as the
- <filename>php</filename> (called <filename>php.exe</filename> on Windows)
- binary.
- </para>
+ <literal>./configure</literal>. Since <literal>PHP 4.3.0</literal> the
+ <literal>CLI SAPI</literal> is no longer experimental and the option
+ <literal>--enable-cli</literal> is on by default. You may use
+ <literal>--disable-cli</literal> to disable it.
+ </para>
+ <para>
+ 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 <literal>make</literal>, both the CGI and CLI are built and
+ placed as <literal>sapi/cgi/php</literal> and <literal>sapi/cgi/php</literal>
+ respectfully, in your php source directory. You will note that both are
+ named <literal>php</literal>. What happens during <literal>make
+ install</literal> depends on your configure
+ line. If a module SAPI is chosen during configure, such as apxs, or the
+ <literal> --disable-cgi</literal> option is used, the CLI is copied to
+ <literal>{PREFIX}/bin/php</literal> during <literal>make install</literal>
+ otherwise the CGI is placed there. So, for example, if <literal>--with--apxs
+ </literal> is in your configure line then the CLI is copied to
+ <literal>{PREFIX}/bin/php</literal> during <literal>make
+ install</literal>. If you want to override the installation of the CGI
+ binary, use <literal>make install-cli</literal> after <literal>make
+ install</literal>. Alternatively you can specify <literal>--disable-cgi
+ </literal> in your configure line.
+ </para>
+ <note>
+ <para>
+ Because both <literal>--enable-cli</literal> and <literal>
+ --enable-cgi</literal> are enabled by default, simply having
+ <literal>--enable-cli</literal> in your configure line does
+ not necessarily mean the CLI will be copied as <literal>
+ {PREFIX}/bin/php</literal> during <literal>make install</literal>.
+ </para>
+ </note>
+ <para>
+ The windows package distributes the CGI as php.exe and has a folder named
+ cli with the CLI in it, so: <literal>cli/php.exe</literal>.
+ </para>
+ <note>
+ <title>What SAPI do I have?</title>
+ <para>
+ While in shell, by typing <literal>php -v</literal> it will tell you
+ whether <literal>php</literal> is CGI or CLI. See also the function
+ <function>php_sapi_name</function> and the constant <constant>
+ PHP_SAPI</constant>.
+ </para>
+ </note>
<para>
Remarkable differences of the <literal>CLI SAPI</literal> compared to other
<literal>SAPI</literal>s:
@@ -199,27 +241,27 @@
<para>
The <literal>CLI SAPI</literal> does <emphasis
role="strong">not</emphasis> change the current directory to the directory
- of the executed script !
+ of the executed script!
</para>
<para>
Example showing the difference to the <literal>CGI SAPI</literal>:
<programlisting role="php">
<![CDATA[
<?php
- /* Our simple test application */
+ /* Our simple test application named test.php*/
echo getcwd(), "\n";
?>
]]>
</programlisting>
</para>
<para>
- When using the <literal>CGI</literal> version, the output is
+ When using the <literal>CGI</literal> version, the output is:
<screen>
<![CDATA[
$ pwd
/tmp
-$ php-cgi -f another_directory/test.php
+$ php -q another_directory/test.php
/tmp/another_directory
]]>
</screen>
@@ -486,8 +528,8 @@
<screen>
<![CDATA[
$ php -v
-PHP 4.3.0-dev (cli), Copyright (c) 1997-2002 The PHP Group
-Zend Engine v1.2.1, Copyright (c) 1998-2002 Zend Technologies
+PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
+Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies
]]>
</screen>
</para>
@@ -957,14 +999,14 @@
<example>
<title>Batch file to run a command line PHP script (script.bat)</title>
<programlisting role="winbat">
-@c:\php\php.exe script.php %1 %2 %3 %4
+@c:\php\cli\php.exe 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
+ CLI <filename>php.exe</filename> in
+ <filename>c:\php\cli\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>.
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
