错误处理

## 简介
这些是错误处理和日志记录的函数。这些函数允许定义自己的错误处理规则，以及修改错误记录的方式。这样就可以更改和加强错误报告以满足需要。

通过日志记录函数，可以将信息直接发送到其他机器、电子邮件（邮件到 pager 网关！）、系统日志等，从而可以有选择的记录和监视应用程序和网站的最重要的部分。

错误报告函数允许自定义错误反馈级别和类型，范围从简单的通知到错误时自定义函数返回。

## 安装/配置

### 需求
构建此扩展不需要其他扩展。

### 安装
使用这些函数不需要安装，它们是 PHP 核心的一部分。

### 运行时配置
这些函数的行为受 php.ini 中的设置影响。

| 名字                     | 默认         | 可修改范围      | 更新日志                         |
|------------------------|------------|------------|------------------------------|
| error_reporting        | NULL       | INI_ALL    | &nbsp;                       |
| display_errors         | "1"        | INI_ALL    | &nbsp;                       |
| display_startup_errors | "1"        | INI_ALL    | PHP 8.0.0 之前，默认值是 "0"。       |
| log_errors             | "0"        | INI_ALL    | &nbsp;                       |
| log_errors_max_len     | "1024"     | INI_ALL    | PHP 8.0.0 起弃用，PHP 8.1.0 起移除。 |
| ignore_repeated_errors | "0"        | INI_ALL    | &nbsp;                       |
| ignore_repeated_source | "0"        | INI_ALL    | &nbsp;                       |
| report_memleaks        | "1"        | INI_ALL    | &nbsp;                       |
| track_errors           | "0"        | INI_ALL    | PHP 7.2.0 起弃用，PHP 8.0.0 起移除  |
| html_errors            | "1"        | INI_ALL    | &nbsp;                       |
| xmlrpc_errors          | "0"        | INI_SYSTEM | &nbsp;                       |
| xmlrpc_error_number    | "0"        | INI_ALL    | &nbsp;                       |
| docref_root            | ""         | INI_ALL    | &nbsp;                       |
| docref_ext             | ""         | INI_ALL    | &nbsp;                       |
| error_prepend_string   | NULL       | INI_ALL    | &nbsp;                       |
| error_append_string    | NULL       | INI_ALL    | &nbsp;                       |
| error_log              | NULL       | INI_ALL    | &nbsp;                       |
| error_log_mode         | 0o644      | INI_ALL    | 自 PHP 8.2.0 起有效              |
| syslog.facility        | "LOG_USER" | INI_SYSTEM | 自 PHP 7.3.0 起可用。             |
| syslog.filter          | "no-ctrl"  | INI_ALL    | 自 PHP 7.3.0 起可用。             |
| syslog.ident           | "php"      | INI_SYSTEM | 自 PHP 7.3.0 起可用。             |

有关 INI_* 样式的更多详情与定义，见 [配置可被设定范围](https://www.php.net/manual/zh/configuration.changes.modes.php "配置可被设定范围")。
这是配置指令的简短说明。

`error_reporting` `int`
设置错误报告级别。该参数可以是表示二进制位字段的任意整数或者常量名称。`error_reporting` 级别和常量是在预定义常量和 `php.ini` 中进行了说明。在程序运行时可以通过 `error_reporting()` 进行设置。另请查看 `display_errors` 指令。

默认值为 `E_ALL`。

PHP 8.0.0 之前，默认值是：E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED。这意味着不会显示 E_NOTICE、 E_STRICT、E_DEPRECATED 级别的错误提示。

> 注意: PHP外的PHP常量
在 PHP 以外（如 httpd.conf）使用 PHP 常量将没有意义，因此在这种情况下需要 int 值来取代。由于错误级别会随着时间的推移而增长，错误级别的最大值（E_ALL）可能会改变。所以考虑使用更大的值来代替 E_ALL 从而覆盖从现在到未来的所有二进制位字段，例如数值 2147483647（将包含所有错误，而不仅仅是 E_ALL）。

`display_errors` `string`
该选项设置是否将错误信息作为输出的一部分打印到屏幕，或者对用户隐藏。

值 "stderr" 将错误发送到 stderr 而不是 stdout。

> 注意:
这是辅助开发的功能，不应在生产系统中使用 (例如连接到互联网的系统)。

> 注意:
尽管 display_errors 也可以在运行时设置 (使用 ini_set())， 但是如果脚本出现致命错误，它不会起到任何作用。因为还没执行所需的运行时操作。

`display_startup_errors` `bool`
即使 display_errors 设置为开启，PHP 也不会显示启动过程中的错误。强烈建议除调试外，都将 display_startup_errors 设置为关闭。

`log_errors` `bool`
设置是否将脚本运行的错误信息记录到服务器错误日志或者 error_log。注意，这是与服务器相关的特定配置项。

> 注意:
在生产环境 web 网站中，强烈建议使用错误日志记录代替错误显示。

`log_errors_max_len` `int`
设置 log_errors 的最大字节数. 在 error_log 中添加有关错误源的信息。默认值为 1024，如果设置为 0 表示不限长度。该长度适用于记录的错误，显示的错误，以及 $php_errormsg，但不适用于显式调用的函数，例如 error_log()。

当使用 `int` 时, 其值以字节来衡量。还可以使用在 FAQ 中描述的速记符。

`ignore_repeated_errors` `bool`
不记录重复的信息。重复的错误必须出现在同一个文件中的同一行代码上，除非 `ignore_repeated_source` 设置为 `true`。

`ignore_repeated_source` `bool`
忽略重复消息时，也忽略消息的来源。当该设置开启时，重复信息将不会记录它是由不同的文件还是不同的源代码行产生的。

`report_memleaks` `bool`
如果这个参数设置为开启（默认），此参数将会显示 Zend 内存管理器检测到的内存泄露报告。此报告将会发送到 Posix 平台上的 stderr。在 Windows 上，将使用 OutputDebugString() 发送到调试器并可以使用 » DbgView 等工具查看。此参数进在调试版本中有效并且需要 error_reporting 包含 E_WARNING。

`track_errors` `bool`
如果开启，最后的一个错误将永远存在于变量 $php_errormsg 中。

`html_errors` `bool`
如果启用，错误消息将包含 HTML 标记。HTML 错误格式会生成可点击的消息，将用户引导至描述错误页面或者导致错误的函数。这些引用跟 docref_root 和 docref_ext 的有关。

如果启用，错误消息将完全是纯文本。

`xmlrpc_errors` `bool`
如果启用，则关闭正常的错误报告，并将错误格式格式化为 XML-RPC 错误信息。

`xmlrpc_error_number` `int`
用作 XML-RPC faultCode 元素的值。

`docref_root` `string`
新的错误信息格式包含了对描述错误或者导致错误的函数的页面引用。为了提供手册的页面，你可以在 PHP 官方站点下载对应语言的手册，并在 ini 中设置网址到本地对应的地址。如果你的本地手册拷贝可以使用 "/manual/" 访问，你就可以简单的设置 docref_root=/manual/。另外你还需要设置 docref_ext 匹配你本地文件的后缀名 `docref_ext=.html`。当然也可以设置一个外部的参考地址。例如你可以设置 `docref_root=http://manual/en/` 或者 `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"`

通常需要在 docref_root 后面以 "/"结尾， 但是在以上的第二种示例情况中不必这么设置。

```php
注意:
这是辅助开发的功能，因为可以快速定位和查看到函数的说明。不应在生产系统中使用 (例如连接到互联网的系统)。
```

`docref_ext` `string`
参见 docref_root。

> 注意:
docref_ext 的值必须以 "." 开头。

`error_prepend_string` `string`
错误信息之前输出的字符串。仅在屏幕上显示错误消息时使用。主要是目的是能够为错误消息添加额带的 HTML 标记。

`error_append_string` `string`
错误信息之后输出的字符串。仅在屏幕上显示错误消息时使用。主要是目的是能够为错误消息添加额带的 HTML 标记。

`error_log` `string`
设置脚本错误将被记录到的文件名称。该文件应该由 Web 服务器用户写入。如果使用特殊值 syslog，则将错误信息发送到系统日志记录器。在 Unix 系统上，使用的是 syslog(3)，而在 Windows 上则为事件日志。参见：syslog()。如果该配置没有设置，则错误信息会被发送到 SAPI 错误记录器。例如，出现在 Apache 的错误日志中，或者在 CLI 中的 stderr。参阅 error_log()。

`error_log_mode` `int`
File mode for the file described set in error_log.

`syslog.facility` `string`
指定记录日志信息的程序类型，仅在 error_log 设置为 "syslog" 时有效。

`syslog.filter` `string`
指定过滤器类型以过滤纪录的消息。允许不加修改的传递字符；all others are written in their hexadecimal representation prefixed with \x.

- all——记录的字符串在换行符处拆分，并且所有字符都原封不动的传递
- ascii——纪录的字符串在换行符处拆分，且转义任何不可打印的 7 位 ASCII 字符
- no-ctrl——纪录的字符串在换行符处拆分，且转义任何不可打印字符
- raw——所有字符都原封不动的传递给系统记录器，换行符处不会拆分 (identical to PHP before 7.3)

此设置通过 error_log 设置为 “syslog” 并调用 syslog() 影响日志记录。

> 注意:
raw 过滤器从 PHP 7.3.8 和 PHP 7.4.0 起可以使用。

Windows 上不支持该指令。

`syslog.ident` `string`
设置每条日志消息前缀的识别字符串（ident string），仅在 error_log 为 "syslog" 时有效。

### 资源类型
此扩展没有定义资源类型。

## 预定义常量

| 值     | 常量  | 说明    | 备注   |
|-------|-------|---------|--------|
| 1     |  E_ERROR (int) | 致命的运行时错误。这类错误一般是不可恢复的情况，例如内存分配导致的问题。后果是导致脚本终止不再继续运行。| &nbsp; |
| 2     | E_WARNING (int) | 运行时警告 (非致命错误)。仅给出提示信息，但是脚本不会终止运行。 | &nbsp; |
| 4     | E_PARSE (int) | 编译时语法解析错误。解析错误仅仅由分析器产生。 | &nbsp; |
| 8     | E_NOTICE (int) | 运行时通知。表示脚本遇到可能会表现为错误的情况，但是在可以正常运行的脚本里面也可能会有类似的通知。 | &nbsp; |
| 16    | E_CORE_ERROR (int) | 在 PHP 初始化启动过程中发生的致命错误。该错误类似 E_ERROR，但是是由 PHP 引擎核心产生的。 | &nbsp; |
| 32    | E_CORE_WARNING (int) | PHP 初始化启动过程中发生的警告 (非致命错误) 。类似 E_WARNING，但是是由 PHP 引擎核心产生的。 | &nbsp; |
| 64    | E_COMPILE_ERROR (int) | 致命编译时错误。类似 E_ERROR，但是是由 Zend 脚本引擎产生的。| &nbsp; |
| 128   | E_COMPILE_WARNING (int) | 编译时警告 (非致命错误)。类似 E_WARNING，但是是由 Zend 脚本引擎产生的。| &nbsp; |
| 256   | E_USER_ERROR (int) | 用户产生的错误信息。类似 E_ERROR，但是是由用户自己在代码中使用 PHP 函数 trigger_error()来产生的。 | &nbsp; |
| 512   | E_USER_WARNING (int) | 用户产生的警告信息。类似 E_WARNING，但是是由用户自己在代码中使用 PHP 函数 trigger_error()来产生的。| &nbsp; |
| 1024  | E_USER_NOTICE (int) | 用户产生的通知信息。类似 E_NOTICE，但是是由用户自己在代码中使用 PHP 函数 trigger_error()来产生的。 | &nbsp; |
| 2048  | E_STRICT (int) | 启用 PHP 对代码的修改建议，以确保代码具有最佳的互操作性和向前兼容性。| &nbsp; |
| 4096  | E_RECOVERABLE_ERROR (int) | 可被捕捉的致命错误。 它表示发生了一个可能非常危险的错误，但是还没有导致PHP引擎处于不稳定的状态。 如果该错误没有被用户自定义句柄捕获 (参见 set_error_handler())，将成为一个 E_ERROR　从而脚本会终止运行。| &nbsp; |
| 8192  | E_DEPRECATED (int) | 运行时通知。启用后将会对在未来版本中可能无法正常工作的代码给出警告。| &nbsp; |
| 16384 | E_USER_DEPRECATED (int) | 用户产生的警告信息。 类似 E_DEPRECATED, 但是是由用户自己在代码中使用PHP函数 trigger_error()来产生的。| &nbsp; |
| 32767 | E_ALL (int) | 所有错误、警告和通知。| &nbsp; |

上面的值（数值或者符号）用于建立一个二进制位掩码，来制定要报告的错误信息。可以使用[按位运算符](https://www.php.net/manual/zh/language.operators.bitwise.php "按位运算符")来组合这些值或者屏蔽某些类型的错误。请注意，在 php.ini 之中，只有'|', '~', '!', '^' 和 '&' 会正确解析。

## 示例
下面我们可以看到错误处理功能在 PHP 中的使用的示例。定义错误处理函数，记录错误信息到文件中（使用 XML 格式），并在发生严重错误时向开发人员发送电子邮件。

示例 #1 在脚本中使用错误句柄
```php
<?php
// 我们将要定义自己的错误处理
error_reporting(0);

// 用户自定义错误处理函数
function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) 
{
    // 错误发生的时间
    $dt = date("Y-m-d H:i:s (T)");

// 定义错误字符串的关联数组
    // 在这里我们只考虑
    // E_WARNING, E_NOTICE, E_USER_ERROR,
    // E_USER_WARNING 和 E_USER_NOTICE
    $errortype = array (
                E_ERROR              => 'Error',
                E_WARNING            => 'Warning',
                E_PARSE              => 'Parsing Error',
                E_NOTICE             => 'Notice',
                E_CORE_ERROR         => 'Core Error',
                E_CORE_WARNING       => 'Core Warning',
                E_COMPILE_ERROR      => 'Compile Error',
                E_COMPILE_WARNING    => 'Compile Warning',
                E_USER_ERROR         => 'User Error',
                E_USER_WARNING       => 'User Warning',
                E_USER_NOTICE        => 'User Notice',
                E_STRICT             => 'Runtime Notice',
                E_RECOVERABLE_ERROR  => 'Catchable Fatal Error'
                );
    // 设置要保存变量跟踪信息的错误类别
    $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
    
    $err = "<errorentry>\n";
    $err .= "\t<datetime>" . $dt . "</datetime>\n";
    $err .= "\t<errornum>" . $errno . "</errornum>\n";
    $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
    $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
    $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
    $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

if (in_array($errno, $user_errors)) {
        $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
    }
    $err .= "</errorentry>\n\n";
    
    // for testing
    // echo $err;

// 记录错误信息到错误日志，并在发生关键用户错误时发送电子邮件
    error_log($err, 3, "/usr/local/php4/error.log");
    if ($errno == E_USER_ERROR) {
        mail("phpdev@example.com", "Critical User Error", $err);
    }
}

function distance($vect1, $vect2) 
{
    if (!is_array($vect1) || !is_array($vect2)) {
        trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
        return NULL;
    }

if (count($vect1) != count($vect2)) {
        trigger_error("Vectors need to be of the same size", E_USER_ERROR);
        return NULL;
    }

for ($i=0; $i<count($vect1); $i++) {
        $c1 = $vect1[$i]; $c2 = $vect2[$i];
        $d = 0.0;
        if (!is_numeric($c1)) {
            trigger_error("Coordinate $i in vector 1 is not a number, using zero", 
                            E_USER_WARNING);
            $c1 = 0.0;
        }
        if (!is_numeric($c2)) {
            trigger_error("Coordinate $i in vector 2 is not a number, using zero", 
                            E_USER_WARNING);
            $c2 = 0.0;
        }
        $d += $c2*$c2 - $c1*$c1;
    }
    return sqrt($d);
}

$old_error_handler = set_error_handler("userErrorHandler");

// 未定义的常量，将产生一个警告
$t = I_AM_NOT_DEFINED;

// 定义一些 "载体"
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);

// 引发一个用户错误
$t1 = distance($c, $b) . "\n";

// 再次引发一个用户错误
$t2 = distance($b, "i am not an array") . "\n";

// 引发一个警告
$t3 = distance($a, $b) . "\n";

?>
```