(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
trigger_error — 生成用户级别的错误/警告/提示消息
用于触发用户错误条件，它可以与内置的错误处理程序一起使用，也可以与已设置为新的错误处理程序的用户定义函数一起使用（set_error_handler()）。
当您需要在运行时对异常生成特定响应时，此函数非常有用。
message此错误的指定错误消息。其长度限制为 1024 字节。超过 1024 字节的任何额外字符都将被截断。
error_level此错误的指定错误类型。它仅适用于E_USER_* 常量族，并将默认为E_USER_NOTICE。
将E_USER_ERROR作为error_level 现在已弃用。请改用抛出Exception 或调用exit()。
始终返回true。
如果error_level不是E_USER_ERROR、E_USER_WARNING、E_USER_NOTICE、E_USER_DEPRECATED之一，则此函数将抛出ValueError。
| 版本 | 描述 |
|---|---|
| 8.4.0 | 将E_USER_ERROR作为error_level 现在已弃用。请改用抛出Exception 或调用exit()。 |
| 8.4.0 | 此函数的返回类型现在为true，而不是bool。 |
| 8.0.0 | 如果指定了无效的error_level，此函数现在将抛出ValueError。之前，它返回false。 |
示例 #1 trigger_error() 示例
有关更详尽的示例，请参阅set_error_handler()。
<?php
$password = $_POST['password'] ?? '';
if ($password === '') {
trigger_error("使用空密码是不安全的", E_USER_WARNING);
}
$hash = password_hash($password, PASSWORD_DEFAULT);
?>message中的HTML实体不会被转义。如果错误要在浏览器中显示，请对消息使用htmlentities()。
其理念是永远不要向用户提供文件名、行号和神秘代码。在使用 set_error_handler() 注册您自己的回调函数（该函数将错误代码记录或通过电子邮件发送给您）之后，使用 trigger_error()，并向用户显示简单的友好消息。
并在需要调试脚本时启用更详细的错误处理函数。在我的 init.php 脚本中，我始终具有
if (_DEBUG_) {
set_error_handler ('debug_error_handler');
}
else {
set_error_handler ('nice_error_handler');
}注意，trigger_error() 完全无法用于在 $php_errormsg 中传输您自己函数的错误消息
ini_set('track_errors', TRUE);
function x() { trigger_error('MY ERROR'); }
@x();
echo "Error 1: \\"$php_errormsg\\"\\n";
@file_get_contents('/nonexisting');
echo "Error 2: \\"$php_errormsg\\"\\n";
这将输出
Error 1: ""
Error 2: "failed to open stream: No such file or directory"
此行为与 $php_errormsg 的描述一致，该描述指出该变量仅在其发生错误的范围内可用。可以使用如下所示的自定义错误处理程序来解决此问题。但是，我尚未决定是否以这种方式更改语言是好的
function errHandler($errno, $errstr, $errfile, $errline) {
global $php_errormsg; $php_errormsg = $errstr;
}
set_error_handler('errHandler');trigger_error 始终报告调用 trigger_error 的行和文件。这不太有用。
例如
main.php
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>
functions.php
<?php
function doFunction($var) {
if(is_numeric($var)) {
/* 执行某些操作*/
} else {
trigger_error('var 必须是数字');
}
}
?>
将输出“Notice: var must be numeric in functions.php on line 6”
而“Notice: var must be numeric in main.php on line 4” 将更有用
这是一个执行此操作的函数
<?php
function error($message, $level=E_USER_NOTICE) {
$caller = next(debug_backtrace());
trigger_error($message.' in <strong>'.$caller['function'].'</strong> called from <strong>'.$caller['file'].'</strong> on line <strong>'.$caller['line'].'</strong>'."\n<br />error handler", $level);
}
?>
因此，在我们的示例中
main.php
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>
functions.php
<?php
function doFunction($var) {
if(is_numeric($var)) {
/* 执行一些操作*/
} else {
error('var 必须是数字');
}
}
function error($message, $level=E_USER_NOTICE) {
$caller = next(debug_backtrace());
trigger_error($message.' 在 <strong>'.$caller['function'].'</strong> 中调用，来自 <strong>'.$caller['file'].'</strong> 的第 <strong>'.$caller['line'].'</strong> 行' ."\n<br />错误处理程序", $level);
}
?>
现在输出
“Notice: var 必须是数字 在 doFunction 中调用，来自 main.php 的第 4 行”对于那些希望在错误中使用自己的文件或行号（可能使用 debug_backtrace()）而不是 trigger_error() 生成的文件或行号的用户，这里有一个解决方案
创建一个自定义函数来处理 E_USER_ERROR，该函数只输出错误类型和消息，同时排除 trigger_error() 报告的行号和文件。如果需要，您也可以将其配置为处理用户警告和通知（在下面的示例中我做了）。
<?php
function error_handler($level, $message, $file, $line, $context) {
// 我们自己处理用户错误、警告和通知
if($level === E_USER_ERROR || $level === E_USER_WARNING || $level === E_USER_NOTICE) {
echo '<strong>错误：</strong> '.$message;
return(true); // 并阻止 PHP 错误处理程序继续
}
return(false); // 否则，使用 PHP 的错误处理程序
}
function trigger_my_error($message, $level) {
// 获取调用函数的调用者及其详细信息
$callee = next(debug_backtrace());
// 触发相应的错误
trigger_error($message.' 在 <strong>'.$callee['file'].'</strong> 的第 <strong>'.$callee['line'].'</strong> 行', $level);
}
// 使用我们自定义的处理程序
set_error_handler('error_handler');
//-------------------------------
// 演示用法：
//-------------------------------
function abc($str) {
if(!is_string($str)) {
trigger_my_error('abc() 期望参数 1 为字符串', E_USER_ERROR);
}
}
abc('Hello world!'); // 工作正常
abc(18); // 错误：abc() 期望参数 1 为字符串 在 [FILE].php 的第 31 行
?>
这是一个非常简单的概念，我相信你们大多数人都知道这一点，但对于那些不知道的人来说，让它作为一个很好的例子吧！如果 error_type 是 E_USER_ERROR，则 trigger_error 会抛出致命错误，脚本在此行之后停止。
<?php
$msg = '这是测试消息';
trigger_error('错误消息', E_USER_ERROR); // 脚本在此行之后停止...
echo $msg; // 此行不会出现...
?>如果 $error_level 等于或高于 E_USER_ERROR，则函数 trigger_error 将终止脚本。
如果编写自己的错误处理程序，则必须自己执行这些操作。
示例，其中我们假设全局 LOG 常量指向 PSR2 日志接口。
<?php
set_error_handler( function ($errno, $errstr, $errfile, $errline) {
// 错误使用 @ 运算符被抑制
if( 0 === error_reporting() ) {
return false;
}
switch($errno) {
default:
LOG->error( "未知错误类型：["$errno"] "$errstr", [ 'file' => $errfile, '@' => $errline ] );
exit(1);
case E_USER_ERROR: // 直接执行下一条case
case E_WARNING: // 将 PHP 警告视为错误
LOG->error( $errstr, [ 'file' => $errfile, '@' => $errline ] );
exit(1);
case E_USER_DEPRECATED:
case E_DEPRECATED:
LOG->error( "已弃用 "$errstr", [ 'file' => $errfile, '@' => $errline ] );
break;
case E_USER_WARNING: // 直接执行下一条case
case E_NOTICE: // 将 PHP 通知视为警告
LOG->warning( $errstr, [ 'file' => $errfile, '@' => $errline ] );
break;
case E_USER_NOTICE:
LOG->notice( $errstr, [ 'file' => $errfile, '@' => $errline ] );
break;
case E_ERROR: // 直接执行下一条case
case E_RECOVERABLE_ERROR:
LOG->critical( $errstr, [ 'file' => $errfile, '@' => $errline ] );
exit(1);
}
/* 不要执行 PHP 内部错误处理程序 */
return true;
} );
?>