archived-doc-zh/reference/errorfunc/ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 72a6f3d35e914602703b698a5d8f52732b61ed3e Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<section xml:id="errorfunc.configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.runtime;
 &extension.runtime;
 <para>
  <table>
   <title>错误和日志记录配置选项</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry>&Name;</entry>
      <entry>&Default;</entry>
      <entry>&Changeable;</entry>
      <entry>&Changelog;</entry>
     </row>
    </thead>
    <tbody>
    <row>
     <entry><link linkend="ini.error-reporting">error_reporting</link></entry>
     <entry>NULL</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.display-errors">display_errors</link></entry>
     <entry>"1"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.display-startup-errors">display_startup_errors</link></entry>
     <entry>"1"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry>PHP 8.0.0 之前，默认值是 <literal>"0"</literal>。</entry>
    </row>
    <row>
     <entry><link linkend="ini.log-errors">log_errors</link></entry>
     <entry>"0"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.log-errors-max-len">log_errors_max_len</link></entry>
     <entry>"1024"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry>PHP 8.0.0 起弃用，PHP 8.1.0 起移除。</entry>
    </row>
    <row>
     <entry><link linkend="ini.ignore-repeated-errors">ignore_repeated_errors</link></entry>
     <entry>"0"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.ignore-repeated-source">ignore_repeated_source</link></entry>
     <entry>"0"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.report-memleaks">report_memleaks</link></entry>
     <entry>"1"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.track-errors">track_errors</link></entry>
     <entry>"0"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry>PHP 7.2.0 起弃用，PHP 8.0.0 起移除</entry>
    </row>
    <row>
     <entry><link linkend="ini.html-errors">html_errors</link></entry>
     <entry>"1"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.xmlrpc-errors">xmlrpc_errors</link></entry>
     <entry>"0"</entry>
     <entry><constant>INI_SYSTEM</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.xmlrpc-error-number">xmlrpc_error_number</link></entry>
     <entry>"0"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.docref-root">docref_root</link></entry>
     <entry>""</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.docref-ext">docref_ext</link></entry>
     <entry>""</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.error-prepend-string">error_prepend_string</link></entry>
     <entry>NULL</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.error-append-string">error_append_string</link></entry>
     <entry>NULL</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.error-log">error_log</link></entry>
     <entry>NULL</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry></entry>
    </row>
    <row>
     <entry><link linkend="ini.error-log-mode">error_log_mode</link></entry>
     <entry>0o644</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry>自 PHP 8.2.0 起有效</entry>
    </row>
    <row>
     <entry><link linkend="ini.syslog.facility">syslog.facility</link></entry>
     <entry>"LOG_USER"</entry>
     <entry><constant>INI_SYSTEM</constant></entry>
     <entry>自 PHP 7.3.0 起可用。</entry>
    </row>
    <row>
     <entry><link linkend="ini.syslog.filter">syslog.filter</link></entry>
     <entry>"no-ctrl"</entry>
     <entry><constant>INI_ALL</constant></entry>
     <entry>自 PHP 7.3.0 起可用。</entry>
    </row>
    <row>
     <entry><link linkend="ini.syslog.ident">syslog.ident</link></entry>
     <entry>"php"</entry>
     <entry><constant>INI_SYSTEM</constant></entry>
     <entry>自 PHP 7.3.0 起可用。</entry>
    </row>
    </tbody>
   </tgroup>
  </table>
  &ini.php.constants;
 </para>

 &ini.descriptions.title;

 <para>
  <variablelist>
   <varlistentry xml:id="ini.error-reporting">
    <term>
     <parameter>error_reporting</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      设置错误报告级别。该参数可以是表示二进制位字段的任意整数或者常量名称。error_reporting
      级别和常量是在<link linkend="errorfunc.constants">预定义常量</link>和 &php.ini;
      中进行了说明。在程序运行时可以通过 <function>error_reporting</function> 进行设置。另请查看
      <link linkend="ini.display-errors">display_errors</link> 指令。
     </para>
     <para>
      默认值为 <constant>E_ALL</constant>。
     </para>
     <para>
      PHP 8.0.0 之前，默认值是：<userinput><constant>E_ALL</constant> &amp; ~<constant>E_NOTICE</constant> &amp;
      ~<constant>E_STRICT</constant> &amp; ~<constant>E_DEPRECATED</constant></userinput>。这意味着不会显示 
      <constant>E_NOTICE</constant>、 <constant>E_STRICT</constant>、<constant>E_DEPRECATED</constant>
      级别的错误提示。
     </para>
     <note>
      <title>PHP外的PHP常量</title>
      <para>
       在 PHP 以外（如 <filename>httpd.conf</filename>）使用 PHP 常量将没有意义，因此在这种情况下需要 <type>int</type>
       值来取代。由于错误级别会随着时间的推移而增长，错误级别的最大值（<constant>E_ALL</constant>）可能会改变。所以考虑使用更大的值来代替
       <constant>E_ALL</constant> 从而覆盖从现在到未来的所有二进制位字段，例如数值
       <literal>2147483647</literal>（将包含所有错误，而不仅仅是 <constant>E_ALL</constant>）。
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.display-errors">
    <term>
     <parameter>display_errors</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      该选项设置是否将错误信息作为输出的一部分打印到屏幕，或者对用户隐藏。
     </para>
     <para>
      值 <literal>"stderr"</literal> 将错误发送到 <literal>stderr</literal>
      而不是 <literal>stdout</literal>。
     </para>
     <note>
      <para>
      这是辅助开发的功能，不应在生产系统中使用 (例如连接到互联网的系统)。
      </para>
     </note>
     <note>
      <para>
       尽管 display_errors 也可以在运行时设置 (使用 <function>ini_set</function>)，
       但是如果脚本出现致命错误，它不会起到任何作用。因为还没执行所需的运行时操作。
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.display-startup-errors">
    <term>
     <parameter>display_startup_errors</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      即使 display_errors 设置为开启，PHP 也不会显示启动过程中的错误。强烈建议除调试外，都将 display_startup_errors 设置为关闭。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.log-errors">
    <term>
     <parameter>log_errors</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      设置是否将脚本运行的错误信息记录到服务器错误日志或者 <link linkend="ini.error-log">error_log</link>。注意，这是与服务器相关的特定配置项。
     </para>
     <note>
      <para>
       在生产环境 web 网站中，强烈建议使用错误日志记录代替错误显示。
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.log-errors-max-len">
    <term>
     <parameter>log_errors_max_len</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      设置 log_errors 的最大字节数. 在 <link linkend="ini.error-log">error_log</link>
      中添加有关错误源的信息。默认值为 1024，如果设置为 0 表示不限长度。该长度适用于记录的错误，显示的错误，以及
      <varname>$php_errormsg</varname>，但不适用于显式调用的函数，例如 <function>error_log</function>。
     </para>

     &ini.shorthandbytes;

    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.ignore-repeated-errors">
    <term>
     <parameter>ignore_repeated_errors</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      不记录重复的信息。重复的错误必须出现在同一个文件中的同一行代码上，除非
      <link linkend="ini.ignore-repeated-source">ignore_repeated_source</link>
      设置为 true。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.ignore-repeated-source">
    <term>
     <parameter>ignore_repeated_source</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      忽略重复消息时，也忽略消息的来源。当该设置开启时，重复信息将不会记录它是由不同的文件还是不同的源代码行产生的。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.report-memleaks">
    <term>
     <parameter>report_memleaks</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      如果这个参数设置为开启（默认），此参数将会显示 Zend
      内存管理器检测到的内存泄露报告。此报告将会发送到 Posix 平台上的
      stderr。在 Windows 上，将使用 OutputDebugString()
      发送到调试器并可以使用 <link xlink:href="&url.dbgview;">DbgView</link>
      等工具查看。此参数进在调试版本中有效并且需要
      <link linkend="ini.error-reporting">error_reporting</link> 包含
      <constant>E_WARNING</constant>。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.track-errors">
    <term>
     <parameter>track_errors</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      如果开启，最后的一个错误将永远存在于变量 <varname>$php_errormsg</varname> 中。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.html-errors">
    <term>
     <parameter>html_errors</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      如果启用，错误消息将包含 HTML 标记。HTML 错误格式会生成可点击的消息，将用户引导至描述错误页面或者导致错误的函数。这些引用跟
      <link linkend="ini.docref-root">docref_root</link> 和
      <link linkend="ini.docref-ext">docref_ext</link> 的有关。
     </para>
     <para>
      如果禁用，错误消息将完全是纯文本。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.xmlrpc-errors">
    <term>
     <parameter>xmlrpc_errors</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      如果启用，则关闭正常的错误报告，并将错误格式格式化为 XML-RPC 错误信息。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.xmlrpc-error-number">
    <term>
     <parameter>xmlrpc_error_number</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      用作 XML-RPC faultCode 元素的值。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.docref-root">
    <term>
     <parameter>docref_root</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      新的错误信息格式包含了对描述错误或者导致错误的函数的页面引用。为了提供手册的页面，你可以在 PHP
      官方站点下载对应语言的手册，并在 ini 中设置网址到本地对应的地址。如果你的本地手册拷贝可以使用
      <literal>"/manual/"</literal> 访问，你就可以简单的设置
      <userinput>docref_root=/manual/</userinput>。另外你还需要设置 docref_ext 匹配你本地文件的后缀名 
      <userinput>docref_ext=.html</userinput>。当然也可以设置一个外部的参考地址。例如你可以设置
      <userinput>docref_root=http://manual/en/</userinput> 或者
      <userinput>docref_root="http://landonize.it/?how=url&amp;theme=classic&amp;filter=Landon
      &amp;url=http%3A%2F%2Fwww.php.net%2F"</userinput>
     </para>
     <para>
      通常需要在 docref_root 后面以 <literal>"/"</literal>结尾，
      但是在以上的第二种示例情况中不必这么设置。
     </para>
     <note>
      <para>
       这是辅助开发的功能，因为可以快速定位和查看到函数的说明。不应在生产系统中使用 (例如连接到互联网的系统)。
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.docref-ext">
    <term>
     <parameter>docref_ext</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      参见 <link linkend="ini.docref-root">docref_root</link>。
     </para>
     <note>
      <para>
       docref_ext 的值必须以 <literal>"."</literal> 开头。
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.error-prepend-string">
    <term>
     <parameter>error_prepend_string</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      错误信息之前输出的字符串。仅在屏幕上显示错误消息时使用。主要是目的是能够为错误消息添加额带的 HTML 标记。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.error-append-string">
    <term>
     <parameter>error_append_string</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      错误信息之后输出的字符串。仅在屏幕上显示错误消息时使用。主要是目的是能够为错误消息添加额带的 HTML 标记。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.error-log">
    <term>
     <parameter>error_log</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      设置脚本错误将被记录到的文件名称。该文件应该由 Web 服务器用户写入。如果使用特殊值
      <literal>syslog</literal>，则将错误信息发送到系统日志记录器。在 Unix
      系统上，使用的是 syslog(3)，而在 Windows 
      上则为事件日志。参见：<function>syslog</function>。如果该配置没有设置，则错误信息会被发送到
      SAPI 错误记录器。例如，出现在 Apache 的错误日志中，或者在 CLI 中的
      <literal>stderr</literal>。参阅 <function>error_log</function>。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.error-log-mode">
    <term>
     <parameter>error_log_mode</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      File mode for the file described set in
      <link linkend="ini.error-log">error_log</link>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.syslog.facility">
    <term>
     <parameter>syslog.facility</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
       指定记录日志信息的程序类型，仅在 <link linkend="ini.error-log">error_log</link> 设置为 "syslog" 时有效。
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.syslog.filter">
    <term>
     <parameter>syslog.filter</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      指定过滤器类型以过滤纪录的消息。允许不加修改的传递字符；all others are written in their
      hexadecimal representation prefixed with <literal>\x</literal>.
      <itemizedlist>
       <listitem>
        <simpara><literal>all</literal>——记录的字符串在换行符处拆分，并且所有字符都原封不动的传递
        </simpara>
       </listitem>
       <listitem>
        <simpara><literal>ascii</literal>——纪录的字符串在换行符处拆分，且转义任何不可打印的 7 位 ASCII 字符
        </simpara>
       </listitem>
       <listitem>
        <simpara><literal>no-ctrl</literal>——纪录的字符串在换行符处拆分，且转义任何不可打印字符
        </simpara>
       </listitem>
       <listitem>
        <simpara><literal>raw</literal>——所有字符都原封不动的传递给系统记录器，换行符处不会拆分 (identical to PHP before 7.3)
        </simpara>
       </listitem>
      </itemizedlist>
      此设置通过 <link linkend="ini.error-log">error_log</link> 设置为 “syslog” 并调用 <function>syslog</function> 影响日志记录。
     </para>
     <note>
      <para>
       <literal>raw</literal> 过滤器从 PHP 7.3.8 和 PHP 7.4.0 起可以使用。
      </para>
     </note>
     <simpara>
      Windows 上不支持该指令。
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="ini.syslog.ident">
    <term>
     <parameter>syslog.ident</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
       设置每条日志消息前缀的识别字符串（ident string），仅在 <link linkend="ini.error-log">error_log</link> 为 "syslog" 时有效。
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
</section>

<!-- 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
-->