mirror of
https://github.com/php/doc-zh.git
synced 2026-03-23 22:52:08 +01:00
8ea9542a94
- unix/openbsd.xml: translate untranslated English paragraphs - fpm/configuration.xml: fix <type>in</type> → <type>int</type> typo - unix/nginx.xml: fix duplicated SAPI SAPI → FPM SAPI - ini.xml: fix virtualhost → ini_set translation error
484 lines
18 KiB
XML
Executable File
484 lines
18 KiB
XML
Executable File
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- $Revision$ -->
|
||
<!-- EN-Revision: 9ab074d32484672f93e5d822f42fb94ae9088207 Maintainer: dallas Status: ready -->
|
||
<!-- CREDITS: mowangjuanzi -->
|
||
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
<title>运行时配置</title>
|
||
|
||
<sect1 xml:id="configuration.file">
|
||
<title>配置文件</title>
|
||
|
||
<simpara>
|
||
配置文件（&php.ini;）在 PHP 启动时被读取。对于服务器模块版本的 PHP，仅在 web
|
||
服务器启动时读取一次。对于
|
||
<acronym>CGI</acronym> 和 <acronym>CLI</acronym> 版本，每次调用都会读取。
|
||
</simpara>
|
||
<para>
|
||
&php.ini; 的搜索路径如下（按顺序）：
|
||
<itemizedlist>
|
||
<listitem>
|
||
<simpara>
|
||
SAPI 模块所指定的位置（Apache 2 中的 <literal>PHPIniDir</literal>
|
||
指令，CGI 和 CLI 中的 <literal>-c</literal>
|
||
命令行选项）。
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
<varname>PHPRC</varname> 环境变量。
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
可以为不同版本的 PHP 指定不同的 <literal>php.ini</literal>
|
||
文件位置。注册表目录所在的位置取决于你的系统是 32 位还是 64 位。32-bit
|
||
的 PHP 运行在 32-bit 的系统或 64-bit 的 PHP 运行在 64-bit 系统时使用 <literal>[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>
|
||
32-bit 的 PHP 运行在 64-bit 的系统上时，则使用 <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>] 替代。
|
||
系统版本跟 PHP 版本架构一致时，会按以下顺序依次进行检查：
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>，
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> 和
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>，其中的
|
||
x，y 和 z 指的是 PHP 主版本号，次版本号和发行批次。
|
||
对于 32 bit 版本的 PHP 运行在 64 bit 系统上的情况，则会按以下顺序依次进行检查：
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>，
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> 和
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>，其中的
|
||
x，y 和 z 指的是 PHP 主版本号，次版本号和发行批次。如果在其中任何目录下的
|
||
<literal>IniFilePath</literal> 有键值，则第一个值将被用作
|
||
<literal>php.ini</literal> 的位置（仅适用于 Windows）。
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> 内 <literal>IniFilePath</literal> 的值（Windows 注册表位置）。
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
当前工作目录（对于 CLI）。
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
web 服务器目录（对于 SAPI 模块）或 PHP 所在目录（Windows 下其它情况）。
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
Windows 目录（<filename class="directory">C:\windows</filename>
|
||
或 <filename class="directory">C:\winnt</filename>），或
|
||
<literal>--with-config-file-path</literal> 编译时选项指定的位置。
|
||
</simpara>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
如果存在 <filename>php-SAPI.ini</filename>（SAPI 是当前所用的 SAPI
|
||
名称，因此实际文件名为 <filename>php-cli.ini</filename> 或
|
||
<filename>php-apache.ini</filename> 等），则会用它替代 &php.ini;。SAPI
|
||
的名称可以用 <function>php_sapi_name</function> 来测定。
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Apache web 服务器在启动时会把目录转到根目录，这将导致 PHP 尝试在根目录下读取
|
||
&php.ini;，如果存在的话。
|
||
</para>
|
||
</note>
|
||
<simpara>
|
||
可以在如下所示的 &php.ini; 配置值中引用环境变量。自 PHP 8.3.0 起，可以指定一个后备值，当引用的变量未定义时使用该值。
|
||
</simpara>
|
||
<example>
|
||
<title>&php.ini; 中的环境变量</title>
|
||
<programlisting role="ini">
|
||
<![CDATA[
|
||
; PHP_MEMORY_LIMIT 来自于环境变量的值
|
||
memory_limit = ${PHP_MEMORY_LIMIT}
|
||
; 如果 PHP_MAX_EXECUTION_TIME 未定义，将回退到 30
|
||
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
<para>
|
||
由扩展库处理的 &php.ini; 指令，其文档分别在各扩展库的页面。<link
|
||
linkend="ini">内核配置选项</link>见附录。不过也许不是所有的 PHP
|
||
指令都在手册中有文档说明。要得到自己的 PHP 版本中的配置指令完整列表，请阅读
|
||
&php.ini; 文件，其中都有注释。此外，也许从 Git 得到的<link
|
||
xlink:href="&url.php.git.phpini;">最新版 &php.ini;</link> 也有帮助。
|
||
</para>
|
||
<para>
|
||
<example>
|
||
<title>&php.ini; 示例</title>
|
||
<programlisting role="ini">
|
||
<![CDATA[
|
||
; any text on a line after an unquoted semicolon (;) is ignored
|
||
[php] ; section markers (text within square brackets) are also ignored
|
||
; Boolean values can be set to either:
|
||
; true, on, yes
|
||
; or false, off, no, none
|
||
register_globals = off
|
||
track_errors = yes
|
||
|
||
; you can enclose strings in double-quotes
|
||
include_path = ".:/usr/local/lib/php"
|
||
|
||
; backslashes are treated the same as any other character
|
||
include_path = ".;c:\php\lib"
|
||
]]>
|
||
</programlisting>
|
||
<!-- TODO: add more details about values and expressions -->
|
||
</example>
|
||
</para>
|
||
<para>
|
||
在 .ini 文件内可能会引用已存在的 .ini
|
||
变量。例如：<literal>open_basedir = ${open_basedir}
|
||
":/new/dir"</literal>。
|
||
</para>
|
||
<sect2 xml:id="configuration.file.scan">
|
||
<title>扫描路径配置</title>
|
||
|
||
<para>
|
||
可以通过配置，让 PHP 在读完 &php.ini; 后，扫描指定路径中的附加 .ini 配置文件。编译时通过
|
||
<option role="configure">--with-config-file-scan-dir</option>
|
||
参数来指定要扫描的目录。扫描路径也可以通过环境变量
|
||
<varname>PHP_INI_SCAN_DIR</varname> 来设置。
|
||
</para>
|
||
|
||
<para>
|
||
通过在扫描路径配置中加入特定系统的目录分隔符（Windows、NetWare
|
||
和 RISC OS 下是 <literal>;</literal>；其它操作系统下是 <literal>:</literal>；该值可以通过
|
||
PHP 常量 <constant>PATH_SEPARATOR</constant> 获取），还可以设置多个扫描路径。如果
|
||
<varname>PHP_INI_SCAN_DIR</varname> 为空，PHP 一样会扫描在编译时指定的
|
||
<option role="configure">--with-config-file-scan-dir</option> 此路径。
|
||
</para>
|
||
|
||
|
||
|
||
<para>
|
||
对于每个目录而言，PHP 会以首字符顺序为优先级，扫描该目录下所有的 <literal>.ini</literal> 结尾的配置文件。所有被截入的配置文件，可以通过
|
||
<function>php_ini_scanned_files</function> 函数来获取列表，也可以通过 PHP 命令行加入
|
||
<option>--ini</option> 参数来查看。
|
||
</para>
|
||
|
||
|
||
|
||
<informalexample>
|
||
<screen>
|
||
<![CDATA[
|
||
以下假设 PHP 配置为 --with-config-file-scan-dir=/etc/php.d
|
||
并且目录分隔符为 :
|
||
|
||
$ php
|
||
PHP 会加载 /etc/php.d/*.ini 全部配置文件。
|
||
|
||
$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
|
||
PHP 会加载 /usr/local/etc/php.d/*.ini 全部配置文件。
|
||
|
||
$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
|
||
PHP 会加载 /etc/php.d/*.ini 下的全部配置文件，然后加载
|
||
/usr/local/etc/php.d/*.ini 下的全部配置文件。
|
||
|
||
$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
|
||
PHP 会加载 /usr/local/etc/php.d/*.ini 下的全部配置文件，然后加载
|
||
/etc/php.d/*.ini 下的全部配置文件。
|
||
]]>
|
||
</screen>
|
||
</informalexample>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 xml:id="configuration.file.per-user">
|
||
<title>.user.ini 文件</title>
|
||
|
||
<simpara>
|
||
PHP 支持基于每个目录的 INI 文件配置。此类文件
|
||
<emphasis>仅</emphasis>被 CGI／FastCGI SAPI 处理。此功能使得 PECL 的 htscanner
|
||
扩展作废。如果你的 PHP 以模块化运行在 Apache 里，则用 &htaccess; 文件有同样效果。
|
||
</simpara>
|
||
|
||
<simpara>
|
||
除了主 &php.ini; 之外，PHP 还会在每个目录下扫描 INI
|
||
文件，从被执行的 PHP 文件所在目录开始一直上升到 web
|
||
根目录（<varname>$_SERVER['DOCUMENT_ROOT']</varname>
|
||
所指定的）。如果被执行的 PHP 文件在 web 根目录之外，则只扫描该目录。
|
||
</simpara>
|
||
<simpara>
|
||
在 .user.ini 风格的 INI 文件中只有具有 <constant>INI_PERDIR</constant>
|
||
和 <constant>INI_USER</constant> 模式的 INI
|
||
设置可被识别。
|
||
</simpara>
|
||
|
||
<simpara>
|
||
两个新的 INI 指令，
|
||
<link linkend="ini.user-ini.filename">user_ini.filename</link> 和
|
||
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
|
||
控制着用户 INI 文件的使用。
|
||
</simpara>
|
||
|
||
<simpara>
|
||
<link linkend="ini.user-ini.filename">user_ini.filename</link> 设定了 PHP
|
||
会在每个目录下搜寻的文件名；如果设定为空字符串则 PHP
|
||
不会搜寻。默认值是 <literal>.user.ini</literal>。
|
||
</simpara>
|
||
|
||
<simpara>
|
||
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> 控制着重新读取用户
|
||
INI 文件的间隔时间。默认是 300 秒（5 分钟）。
|
||
</simpara>
|
||
</sect1>
|
||
|
||
<sect1 xml:id="configuration.changes.modes">
|
||
<title>配置可被设定范围</title>
|
||
|
||
<para>
|
||
这些模式决定着一个 PHP
|
||
的指令在何时何地，是否能够被设定。手册中的每个指令都有其所属的模式。例如有些指令可以在
|
||
PHP 脚本中用 <function>ini_set</function> 来设定，而有些则只能在
|
||
&php.ini; 或 &httpd.conf; 中。
|
||
</para>
|
||
|
||
<para>
|
||
例如
|
||
<link linkend="ini.output-buffering">output_buffering</link>
|
||
指令是属于
|
||
<constant>INI_PERDIR</constant>，因而就不能用
|
||
<function>ini_set</function> 来设定。但是
|
||
<link linkend="ini.display-errors">display_errors</link>
|
||
指令是属于
|
||
<constant>INI_ALL</constant> 因而就可以在任何地方被设定，包括
|
||
<function>ini_set</function>。
|
||
</para>
|
||
|
||
<para>
|
||
<variablelist>
|
||
<!--
|
||
Replace everything inside the <variablelist> element with an <xi:include>
|
||
once libxml2 gets XInclude 1.1 attribute copying support.
|
||
The below <xi:include> will include the appropriate elements
|
||
but needs all top-level xml:id's removed (see XInclude 1.1 set-xml-id).
|
||
|
||
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('constant.ini-mode')/*)"><xi:fallback/></xi:include>
|
||
-->
|
||
<title>INI 模式常量</title>
|
||
<varlistentry>
|
||
<term>
|
||
<constant>INI_USER</constant>
|
||
(<type>int</type>)
|
||
</term>
|
||
<listitem>
|
||
<simpara>
|
||
可以在用户脚本（如使用 <function xmlns="http://docbook.org/ns/docbook">ini_set</function>）或 <link xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.windows">Windows
|
||
注册表</link>中设置条目。可以在 &user-ini; 中设置条目
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<constant>INI_PERDIR</constant>
|
||
(<type>int</type>)
|
||
</term>
|
||
<listitem>
|
||
<simpara>
|
||
可以在 &php.ini;、&htaccess;、&httpd.conf; 或 &user-ini; 中设置条目
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<constant>INI_SYSTEM</constant>
|
||
(<type>int</type>)
|
||
</term>
|
||
<listitem>
|
||
<simpara>
|
||
可以在 &php.ini; 或 &httpd.conf; 中设置条目
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<constant>INI_ALL</constant>
|
||
(<type>int</type>)
|
||
</term>
|
||
<listitem>
|
||
<simpara>
|
||
条目可以设置在任何地方
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 xml:id="configuration.changes">
|
||
<title>怎样修改配置设定</title>
|
||
|
||
<sect2 xml:id="configuration.changes.apache">
|
||
<title>PHP 运行于 Apache 模块方式</title>
|
||
<simpara>
|
||
当使用 PHP 作为 Apache 模块时，也可以用 Apache
|
||
的配置文件（例如 &httpd.conf;）和 &htaccess;
|
||
文件中的指令来修改 PHP 的配置设定。需要有“AllowOverride
|
||
Options”或“AllowOverride All”权限才可以。
|
||
</simpara>
|
||
|
||
<para>
|
||
有几个 Apache 指令可以使用户在 Apache
|
||
配置文件内部修改 PHP 的配置。哪些指令属于
|
||
<constant>INI_ALL</constant>、<constant>INI_PERDIR</constant>
|
||
或 <constant>INI_SYSTEM</constant> 中的哪一个，请参考附录中的
|
||
<link linkend="ini.list">php.ini 配置选项列表</link>。
|
||
</para>
|
||
|
||
<para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<systemitem role="directive">php_value</systemitem>
|
||
<parameter>name</parameter>
|
||
<parameter>value</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
设定指定的值。只能用于
|
||
<constant>INI_ALL</constant> 或 <constant>INI_PERDIR</constant>
|
||
类型的指令。要清除先前设定的值，把 value 设为 <literal>none</literal>。
|
||
</para>
|
||
<note>
|
||
<simpara>
|
||
不要用 <systemitem role="directive">php_value</systemitem> 设定布尔值。应该用
|
||
<systemitem role="directive">php_flag</systemitem>（见下面）。
|
||
</simpara>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<systemitem role="directive">php_flag</systemitem>
|
||
<parameter>name</parameter>
|
||
<parameter>on|off</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
用来设定布尔值的配置指令。仅能用于
|
||
<constant>INI_ALL</constant> 和
|
||
<constant>INI_PERDIR</constant> 类型的指令。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<systemitem role="directive">php_admin_value</systemitem>
|
||
<parameter>name</parameter>
|
||
<parameter>value</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
设定指定的指令的值。<emphasis>不能用于</emphasis> &htaccess;
|
||
文件。任何用 <systemitem role="directive">php_admin_value</systemitem>
|
||
设定的指令都不能被 &htaccess; 或
|
||
<function>ini_set</function> 覆盖。要清除先前设定的值，把 value 设为 <literal>none</literal>。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<systemitem role="directive">php_admin_flag</systemitem>
|
||
<parameter>name</parameter>
|
||
<parameter>on|off</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
用来设定布尔值的配置指令。<emphasis>不能用于</emphasis> &htaccess;
|
||
文件。任何用 <systemitem role="directive">php_admin_flag</systemitem>
|
||
设定的指令都不能被 &htaccess; 或
|
||
<function>ini_set</function> 覆盖。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
<para>
|
||
<example>
|
||
<title>Apache 配置例子</title>
|
||
<programlisting role="ini">
|
||
<![CDATA[
|
||
<IfModule mod_php5.c>
|
||
php_value include_path ".:/usr/local/lib/php"
|
||
php_admin_flag engine on
|
||
</IfModule>
|
||
<IfModule mod_php4.c>
|
||
php_value include_path ".:/usr/local/lib/php"
|
||
php_admin_flag engine on
|
||
</IfModule>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<caution>
|
||
<para>
|
||
PHP 常量不存在于 PHP 之外。例如在
|
||
&httpd.conf; 中不能使用 PHP 常量如
|
||
<constant>E_ALL</constant> 或 <constant>E_NOTICE</constant> 来设定
|
||
<link linkend="ini.error-reporting">error_reporting</link>
|
||
指令，因为其无意义，实际等于
|
||
<emphasis>0</emphasis>。应该用相应的掩码值来替代。这些常量可以在
|
||
&php.ini; 中使用。
|
||
</para>
|
||
</caution>
|
||
</sect2>
|
||
|
||
<sect2 xml:id="configuration.changes.windows">
|
||
<title>通过 Windows 注册表修改 PHP 配置</title>
|
||
<simpara>
|
||
在 Windows 下运行 PHP 时，可以用 Windows
|
||
注册表以目录为单位来修改配置。配置值存放于注册表项
|
||
<literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>
|
||
下面，子项对应于路径名。例如对于目录
|
||
<literal>c:\inetpub\wwwroot</literal> 的配置值会存放于
|
||
<literal>HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot</literal>
|
||
项下面。其中的设定对于任何位于此目录及其任何子目录的脚本都有效。项中的值的名称是
|
||
PHP 配置指令的名字，值的数据是字符串格式的指令值。值中的 PHP
|
||
常量不被解析。不过只有可修改范围是 <constant>INI_USER</constant>
|
||
的配置值可以用此方法设定，<constant>INI_PERDIR</constant>
|
||
的值就不行。因为这些配置对于每次请求来说是只读的。
|
||
</simpara>
|
||
</sect2>
|
||
|
||
<sect2 xml:id="configuration.changes.other">
|
||
<title>其它接口下的 PHP</title>
|
||
<para>
|
||
无论怎样运行 PHP，都可以在脚本中通过 <function>ini_set</function>
|
||
而在运行时修改某个值。更多信息见手册中
|
||
<function>ini_set</function> 的页面。
|
||
</para>
|
||
<para>
|
||
如果对自己系统中的配置设定及其当前值的完整列表感兴趣，可以运行
|
||
<function>phpinfo</function> 函数并查看其结果的页面。也可以在运行时用
|
||
<function>ini_get</function> 或
|
||
<function>get_cfg_var</function> 取得个别配置指令的值。
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
</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:"~/.phpdoc/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
|
||
-->
|