<?xml version="1.0" encoding="utf-8"?>

<chapter xml:id="features.commandline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<title>PHP 的命令行模式</title>

<!--Introduction: {{{-->

<section xml:id="features.commandline.introduction" annotations="chunk:false">

<title>简介</title>

<para>

&cli.sapi; 主要是使用 PHP 开发 shell 应用。&cli.sapi; 与本章中解释的其它 <acronym>SAPI</acronym>

存在相当多的差异。值得一提的是，尽管 &cli; 和 <literal>CGI</literal> 有很多共同的行为，但它们是不同的 <acronym>SAPI</acronym>。

</para>

<para>

&cli.sapi; 模块会通过默认的 <option

role="configure">--enable-cli</option> 参数设置启用，

也可以在运行 <command>./configure</command> 时用参数

<option role="configure">--disable-cli</option> 来屏蔽。

</para>

<para>

&cli;/<acronym>CGI</acronym> 二进制执行文件的文件名、位置和是否存在会根据

PHP 在系统上的安装而不同。在默认情况下，当运行

<command>make</command> 时，CGI 和 &cli; 都会被编译并且分别放置在

PHP 源文件目录的 <filename>sapi/cgi/php-cgi</filename> 和

<filename>sapi/cli/php</filename> 下。可以注意到两个文件都被命名为了

php。在 <command>make install</command>

的过程中会发生什么取决于配置行。如果在配置的时候选择了一个

<acronym>SAPI</acronym> 模块，如 apxs，或者使用了

<option role="configure">--disable-cgi</option> 参数，则在

<command>make install</command> 的过程中，&cli; 将被拷贝到

<filename>{PREFIX}/bin/php</filename>，除非 <acronym>CGI</acronym>

已经被放置在了那个位置。因此，例如，如果在配置行中有

<option role="configure">--with-apxs</option>，则在

<literal>make install</literal> 的过程中，&cli; 将被拷贝到

<literal>{PREFIX}/bin/php</literal>。如果希望覆盖 <acronym>CGI</acronym>

执行文件的安装，请在 <command>make install</command>

之后运行 <command>make install-cli</command>。或者，也可以在配置行中加上

<option role="configure">--disable-cgi</option> 参数。

</para>

<note>

<para>

由于 <option role="configure">--enable-cli</option> 和

<option role="configure">--enable-cgi</option>

同时默认有效，因此，不必再配置行中加上

<option role="configure">--enable-cli</option> 来使得 &cli; 在

<command>make install</command> 过程中被拷贝到

<filename>{PREFIX}/bin/php</filename>。

</para>

</note>

<para>

在 Windows 发行包中，&cli; 在主目录中的二进制文件名为

<filename>php.exe</filename>。<acronym>CGI</acronym> 版本的文件名为

<filename>php-cgi.exe</filename>。

如果 PHP 配置使用了

<option role="configure">--enable-cli-win32</option>，还会有一个额外的 <filename>

php-win.exe</filename> 随包发布。

它相当于 &cli; 版本，但是 php-win

不输出任何内容，便不提供控制台（不会弹出“DOS 窗口”）。

</para>

<note>

<title>如何得知自己使用的是哪个 SAPI？</title>

<para>

在命令行下，运行 <command>php -v</command> 便能得知该

<filename>php</filename> 是 <acronym>CGI</acronym> 还是 &cli;。请参考函数

<function>php_sapi_name</function> 以及常量 <constant>PHP_SAPI</constant>。

</para>

</note>

<note>

<para>

在命令行中键入

<command>man php</command> 可以查看 Unix <literal>man</literal> 手册页面。

</para>

</note>

</section>

<!--}}}-->

<!--Differences: {{{-->

<section xml:id="features.commandline.differences">

<title>和其它 <acronym>SAPI</acronym> 模块的区别</title>

<para>

以下为 &cli; <acronym>SAPI</acronym> 和其它 <acronym>SAPI</acronym> 模块相比的显著区别：

<itemizedlist>

<listitem>

<para>

与 <acronym>CGI</acronym> <acronym>SAPI</acronym> 不同，其输出没有任何头信息。

</para>

<para>

尽管 <acronym>CGI</acronym> <acronym>SAPI</acronym> 提供了取消 HTTP 头信息的方法，但在

&cli.sapi; 中并不存在类似的方法以开启 HTTP 头信息的输出。

</para>

<para>

&cli; 默认以安静模式开始，但为了保证兼容性，<option>-q</option> 和

<option>--no-header</option> 参数为了向后兼容仍然保留，使得可以使用旧的 <acronym>CGI</acronym> 脚本。

</para>

<para>

在运行时，不会把工作目录改为脚本的当前目录（可以使用

<option>-C</option> 和 <option>--no-chdir</option> 参数来兼容 CGI 模式）。

</para>

<para>

出错时输出纯文本的错误信息（非 <acronym>HTML</acronym> 格式）。

</para>

</listitem>

<listitem>

<para>

&cli.sapi; 强制覆盖了 &php.ini;

中的某些设置，因为这些设置在外壳环境下是没有意义的。

</para>

<para>

<table>

<title>覆盖 &php.ini; 设置选项</title>

<tgroup cols="3">

<thead>

<row>

<entry>设置选项</entry>

<entry>&cli; <acronym>SAPI</acronym> 默认值</entry>

<entry>备注</entry>

</row>

</thead>

<tbody>

<row>

<entry><link linkend="ini.html-errors">html_errors</link></entry>

<entry>&false;</entry>

<entry>

无意义的 <acronym>HTML</acronym>

标记符会使得出错信息很凌乱，所以在外壳下阅读报错信息是十分困难的。因此将该选项的默认值改为 &false;。

</entry>

</row>

<row>

<entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>

<entry>&true;</entry>

<entry>

在命令行模式下，所有来自 <link linkend="function.print"><literal>print</literal></link> 和

<link linkend="function.echo"><literal>echo</literal></link> 的输出将被立即写到输出端，而不作任何地缓冲操作。如果希望延缓或控制标准输出，仍然可以使用

<link linkend="ref.outcontrol">output buffering</link> 设置项。

</entry>

</row>

<row>

<entry><link linkend="ini.max-execution-time">max_execution_time</link></entry>

<entry>0（无限值）</entry>

<entry>

鉴于在外壳环境下使用 PHP 的无穷的可能性，最大运行时间被设置为了无限值。为

web 开发的应用程序可能只需运行几秒钟时间，而外壳应用程序的运行时间可能会长的多。

</entry>

</row>

<row>

<entry><link linkend="ini.register-argc-argv">register_argc_argv</link></entry>

<entry>&true;</entry>

<entry>

<para>

由于该设置为 &true;，将总是可以在 &cli; <acronym>SAPI</acronym>

中访问到 <emphasis>argc</emphasis>（传送给应用程序参数的个数）和

<emphasis>argv</emphasis>（包含有实际参数的数组）。

</para>

<para>

在使用 &cli; <acronym>SAPI</acronym> 时，PHP 变量

<literal>$argc</literal> 和 <literal>$argv</literal>

已被注册并且设定了对应的值。随时可以通过

<varname>$_SERVER</varname> 数组

来访问它们，例如：<varname>$_SERVER['argv']</varname>

</para>

<warning>

<para>

<varname>$argv</varname> 或 <varname>$_SERVER['argv']</varname>

的存在并不能表明脚本一定正在从命令行运行，因为当启用 <link linkend="ini.register-argc-argv">register_argc_argv</link>

时，它们可能在其他上下文中设置。应改为检查 <function>php_sapi_name</function> 返回的值。

<informalexample>

<programlisting role="php">

</programlisting>

</informalexample>

</para>

</warning>

</entry>

</row>

<row>

<entry><link linkend="ini.output-buffering">output_buffering</link></entry>

<entry>&false;</entry>

<entry>

<para>

虽然 &php.ini; 设置已经硬编码为 &false;，

<link linkend="book.outcontrol">输出缓冲控制</link>函数仍然有效。

</para>

</entry>

</row>

<row>

<entry><link linkend="ini.max-input-time">max_input_time</link></entry>

<entry>&false;</entry>

<entry>

<para>

PHP &cli; 不支持 GET、POST、文件上传。

</para>

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<note>

<para>

这些设置无法在设置文件 &php.ini;

或任何指定的其它文件中被初始化为其它值。这些默认值被限制在所有其它的设置文件被解析后改变。

不过，它们的值可以在程序运行的过程中被改变

（尽管对于该运行过程来说，这些设置项是没有意义的，例如 <link linkend="ini.register-argc-argv">register_argc_argv</link>）。

</para>

</note>

<note>

<para>

推荐命令行脚本设置

<link linkend="ini.ignore-user-abort">ignore_user_abort</link>。

更多信息参见 <function>ignore_user_abort</function>。

</para>

</note>

</listitem>

<listitem>

<para>

为了减轻外壳环境下的工作，我们为 <link linkend="features.commandline.io-streams">I/O 流

</link>定义了一系列常量。

</para>

</listitem>

<listitem>

<para>

&cli.sapi;

<emphasis role="strong">不会</emphasis>将当前目录改为已运行的脚本所在的目录。

</para>

<para>

以下范例显示了本模块与 <acronym>CGI</acronym>

<acronym>SAPI</acronym> 模块之间的不同：

<programlisting role="php">

</programlisting>

</para>

<para>

在使用 <literal>CGI</literal> 版本时，其输出为

<screen>

</screen>

</para>

<para>

明显可以看到 PHP 将当前目录改成了刚刚运行过的脚本所在的目录。

</para>

<para>

使用 &cli.sapi; 模式，得到：

<screen>

</screen>

这使得在利用 PHP 编写外壳工具时获得了很大的便利。

</para>

<note>

<para>

可以在命令行运行时给该 <acronym>CGI</acronym> <acronym>SAPI</acronym> 加上

<option>-C</option> 参数，使其支持 &cli.sapi; 的功能。

</para>

</note>

</listitem>

</itemizedlist>

</para>

</section>

<!--}}}-->

<!--Options: {{{-->

<section xml:id="features.commandline.options">

<title>命令行选项</title>

<titleabbrev>选项</titleabbrev>

<para>

PHP 二进制文件可以随时通过执行带 <option>-h</option> 参数的 PHP 命令获取提供的命令行选项列表：

<screen>

</screen>

</para>

<para>

<table>

<title>命令行选项</title>

<tgroup cols="2">

<thead>

<row>

<entry>选项</entry>

<entry>长选项</entry>

<entry>说明</entry>

</row>

</thead>

<tbody>

<row>

<entry>-a</entry>

<entry>--interactive</entry>

<entry>

<para>

运行交互式 PHP。参阅<link linkend="features.commandline.interactive">交互式 shell</link>

章节获取更多信息。

</para>

</entry>

</row>

<row>

<entry>-b</entry>

<entry>--bindpath</entry>

<entry>

<para>

外部 FASTCGI 服务器模式绑定路径（仅 <acronym>CGI</acronym> 可用）。

</para>

</entry>

</row>

<row>

<entry>-C</entry>

<entry>--no-chdir</entry>

<entry>

<para>

不改变脚本的目录（仅 <acronym>CGI</acronym> 可用）。

</para>

</entry>

</row>

<row>

<entry>-q</entry>

<entry>--no-header</entry>

<entry>

<para>

安静模式。禁止输出 <acronym>HTTP</acronym>

头（仅 <acronym>CGI</acronym> 可用）。

</para>

</entry>

</row>

<row>

<entry>-T</entry>

<entry>--timing</entry>

<entry>

<para>

测量脚本重复 <varname>count</varname> 次的执行时间（仅 <acronym>CGI</acronym> 可用）。

</para>

</entry>

</row>

<row>

<entry>-c</entry>

<entry>--php-ini</entry>

<entry>

<para>

在指定目录查找 &php.ini; 或者自定义 <literal>INI</literal>

文件（名称可以不是 &php.ini;），例如：

</para>

<para><informalexample>

<screen>

</screen>

</informalexample></para>

<para>

如果未指定此选项，&php.ini; 将在<link linkend="configuration.file">默认位置</link>搜索。

</para>

</entry>

</row>

<row>

<entry>-n</entry>

<entry>--no-php-ini</entry>

<entry>

<para>

完全忽略 &php.ini;。

</para>

</entry>

</row>

<row>

<entry>-d</entry>

<entry>--define</entry>

<entry>

<para>

允许设置 &php.ini; 中配置指令的值。语法是：

<screen>

<![CDATA[

</screen>

</para>

<para><example>

<title>使用 <literal>-d</literal> 设置 INI 配置的示例</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-e</entry>

<entry>--profile-info</entry>

<entry>

<para>

激活扩展信息模式，用于调试/分析。

</para>

</entry>

</row>

<row>

<entry>-f</entry>

<entry>--file</entry>

<entry>

<para>

解析并执行指定文件。 <option>-f</option>

可选且可以忽略 —— 只需提供需要执行的文件名就足够。

</para>

</entry>

</row>

<row>

<entry>-h and -?</entry>

<entry>--help and --usage</entry>

<entry>

输出命令行选项列表并描述了这些选项的作用。

</entry>

</row>

<row>

<entry>-i</entry>

<entry>--info</entry>

<entry>

调用 <function>phpinfo</function> 并输出结果。如果 PHP

不能正常工作，建议使用命令 <command>php -i</command>

查看在信息表输出之前或者中间某个位置是否有错误消息。注意当使用

<acronym>CGI</acronym> 模式时会输出 <acronym>HTML</acronym>，

这会非常大。

</entry>

</row>

<row>

<entry>-l</entry>

<entry>--syntax-check</entry>

<entry>

<para>

检查语法但不执行指定 PHP 代码。如果未指定文件，则将处理来自标准输入的输入，否则将检查每个文件。成功时，文本

<literal>No syntax errors detected in &lt;filename&gt;</literal> 将写入标准输出。失败时，除了内部解析器错误外，文本

<literal>Errors parsing &lt;filename&gt;</literal> 将写入标准输出。如果在指定文件（或标准输入）中发现任何错误，则将

shell 返回代码设置为 <literal>-1</literal>，否则将 shell 返回代码设置为 <literal>0</literal>。

</para>

<para>

此选项不会找到需要执行代码的致命错误（如未定义的函数）。

</para>

<note>

<para>

在 PHP 8.3.0 之前，只能指定一个要检查的文件。

</para>

</note>

<note>

<para>

此选项不能和 <option>-r</option> 一起使用。

</para>

</note>

</entry>

</row>

<row>

<entry>-m</entry>

<entry>--modules</entry>

<entry>

<para><example>

<title>打印内置（且已加载的） PHP 和 Zend 模块</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-r</entry>

<entry>--run</entry>

<entry>

<para>

允许在命令行内直接执行单行 PHP 代码。

<emphasis role="strong">不需要</emphasis>加上 PHP 开始和结束标识符（<literal>&lt;?php</literal> 和

<literal>?&gt;</literal>），否则将会造成语法错误。

</para>

<note>

<para>

使用这种形式的 PHP 时，应注意避免和 shell 环境进行的命令行参数替换相冲突。

</para>

<example>

<title>当使用双引号时会造成语法错误</title>

<screen>

</screen>

</example>

<para>

这里的问题是在使用双引号 <literal>"</literal> 时 sh/bash 会执行变量替换。

由于 <varname>$foo</varname> 变量没有被定义，因此它将替换为空字符，

从而导致传递给 PHP 执行的代码实际上会变成：

</para>

<informalexample>

<screen>

</screen>

</informalexample>

<para>

正确的方式是使用单引号 <literal>'</literal>

。使用单引号时 sh/bash 不会进行变量替换。

</para>

<example>

<title>使用单引号防止 shell 变量替换</title>

<screen>

</screen>

</example>

<para>

如果使用的 shell 不是 sh/bash，可能会碰到更多的问题 ——

如果有的话，请向 <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>

报告 bug。试图在命令行中使用（ shell/PHP

）变量或者使用反斜杠转义时需要格外小心，因为很容易遇到问题。勿谓言之不预！

</para>

</note>

<note>

<para>

可以在 &cli.sapi; 中使用

<option>-r</option>，但不能在 <emphasis>CGI</emphasis> <acronym>SAPI</acronym> 中使用。

</para>

</note>

<note>

<para>

此选项仅适用于非常基本的代码，因此在此模式下会忽略某些配置指令（如 <link

linkend="ini.auto-prepend-file">auto_prepend_file</link> 和 <link

linkend="ini.auto-append-file">auto_append_file</link>）。

</para>

</note>

</entry>

</row>

<row>

<entry>-B</entry>

<entry>--process-begin</entry>

<entry>

<para>

处理 stdin 之前需要执行的 PHP 代码。

</para>

</entry>

</row>

<row>

<entry>-R</entry>

<entry>--process-code</entry>

<entry>

<para>

对每个输入行都执行的 PHP 代码。

</para>

<para>

此模式下有两个特殊变量：

<varname>$argn</varname> 和 <varname>$argi</varname>。

<varname>$argn</varname> 将包含 PHP 正在处理的行，

<varname>$argi</varname> 将包含正在处理的行号。

</para>

</entry>

</row>

<row>

<entry>-F</entry>

<entry>--process-file</entry>

<entry>

<para>

对每个输入行都执行的 PHP 文件。

</para>

</entry>

</row>

<row>

<entry>-E</entry>

<entry>--process-end</entry>

<entry>

<para>

在处理完输入后执行的 PHP 代码。

</para>

<para><example>

<title>使用 <option>-B</option> 、 <option>-R</option> 、 <option>-E</option>

选项统计项目总行数。

</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-S</entry>

<entry>--server</entry>

<entry>

<para>

启动 <link linkend="features.commandline.webserver">内置 web 服务器</link>.

</para>

</entry>

</row>

<row>

<entry>-t</entry>

<entry>--docroot</entry>

<entry>

为<link linkend="features.commandline.webserver">内置 web 服务器</link>指定文档根目录。

</entry>

</row>

<row>

<entry>-s</entry>

<entry>--syntax-highlight 和 --syntax-highlighting</entry>

<entry>

<para>

为源代码添加语法高亮显示。

</para>

<para>

此选项将使用内部机制解析文件并将生成的 HTML 高亮版本写入到标准输出。

注意它所做的只是生成一块 <literal>&lt;code&gt; [...] &lt;/code&gt;</literal>

HTML 标记，没有 HTML header。

</para>

<note>

<para>

此选项不能和 <option>-r</option> 一起使用。

</para>

</note>

</entry>

</row>

<row>

<entry>-v</entry>

<entry>--version</entry>

<entry>

<para><example>

<title>使用 <option>-v</option> 获取 <acronym>SAPI</acronym>

的名称以及 PHP 和 Zend 的版本号</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-w</entry>

<entry>--strip</entry>

<entry>

<para>

显示忽略注释和空格后的源代码。

</para>

<note>

<para>

此选项不能和 <option>-r</option> 一起使用。

</para>

</note>

</entry>

</row>

<row>

<entry>-z</entry>

<entry>--zend-extension</entry>

<entry>

<para>

加载 Zend 扩展。如果仅指定了文件名，PHP 将尝试从当前系统默认函数库中尝试加载此扩展

（例如在 Linux 上通常是 <filename>/etc/ld.so.conf</filename>）。

传递绝对路径的文件名将不会使用系统库搜索路径。如果用相对路径指定的文件名，则 PHP

仅试图在当前目录的相对目录加载扩展库。

</para>

</entry>

</row>

<row>

<entry></entry>

<entry>--ini</entry>

<entry>

<para>

展示配置文件名和扫描目录。

<example>

<title><literal>--ini</literal> 示例</title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--rf</entry>

<entry>--rfunction</entry>

<entry>

<para>

展示指定函数或者类方法的有关信息（例如参数名称和数量）。

</para>

<para>

如果 PHP 在编译时启用 <link linkend="book.reflection">Reflection</link>

支持，该选项才可以使用。

</para>

<para>

<example>

<title>基础 <literal>--rf</literal> 用法</title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--rc</entry>

<entry>--rclass</entry>

<entry>

<para>

展示指定类的有关信息（常量、属性和方法的列表）。

</para>

<para>

如果 PHP 在编译时启用 <link linkend="book.reflection">Reflection</link>

支持，该选项才可以使用。

</para>

<para>

<example>

<title><literal>--rc</literal> 示例</title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--re</entry>

<entry>--rextension</entry>

<entry>

<para>

展示指定扩展的有关信息（&php.ini; 选项、定义函数、常量和类的列表）。

</para>

<para>

如果 PHP 在编译时启用 <link linkend="book.reflection">Reflection</link>

支持，该选项才可以使用。

</para>

<para>

<example>

<title><literal>--re</literal> 示例</title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--rz</entry>

<entry>--rzendextension</entry>

<entry>

<para>

展示指定 Zend 扩展的配置信息（也可以通过 <function>phpinfo</function> 返回相同信息）。

</para>

</entry>

</row>

<row>

<entry>--ri</entry>

<entry>--rextinfo</entry>

<entry>

<para>

展示指定扩展的配置信息（也可以通过 <function>phpinfo</function> 返回相同信息）。

使用 “main” 作为扩展名可以获取到核心配置信息。

</para>

<para>

<example>

<title><literal>--ri</literal> 示例</title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<note>

<para>

选项 <literal>-rBRFEH</literal>、 <literal>--ini</literal> 、

<literal>--r[fcezi]</literal> 仅可以在 &cli; 中使用。

</para>

</note>

</section>

<!--}}}-->

<!--Usage: {{{-->

<section xml:id="features.commandline.usage">

<title>执行 PHP 文件</title>

<titleabbrev>用法</titleabbrev>

<para>

&cli.sapi; 有三种不同的方法执行 PHP 代码：

<orderedlist>

<listitem>

<para>

让 PHP 运行指定文件。

</para>

<informalexample>

<screen>

</screen>

</informalexample>

<para>

以上两种方法（使用或不使用 <option>-f</option> 参数）都能够运行给定的

<filename>my_script.php</filename> 文件。注意，没有限制可以执行哪种文件，

特别是文件名也不必用 <literal>.php</literal> 作为扩展名。

</para>

</listitem>

<listitem>

<para>

在命令行中直接传递 PHP 代码执行。

</para>

<informalexample>

<screen>