trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — 产生一个用户级别的 error/warning/notice 信息

说明

trigger_error(string $message, int $error_level = E_USER_NOTICE): true

用于触发一个用户级别的错误条件，它能结合内置的错误处理器所关联，或者可以使用用户定义的函数作为新的错误处理程序(set_error_handler())。

该函数在你运行出现异常时，需要产生一个特定的响应时非常有用。

参数

message

该 error 的特定错误信息，长度限制在了 1024 个字节。超过 1024 字节的字符都会被截断。

error_level

该 error 所特定的错误类型。仅 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("Using an empty password is unsafe", E_USER_WARNING);
}
$hash = password_hash($password, PASSWORD_DEFAULT);
?>

注释

警告

在 message 里的 HTML 实体，并不会被转义。如果错误消息要显示在浏览器里，需要对错误消息使用 htmlentities()。

参见

发现了问题？

了解如何改进此页面 • 提交拉取请求 • 报告一个错误
＋添加备注

用户贡献的备注 6 notes

up
54
someone at attbi dot com
21 years ago
the idea is never to give out file names, line numbers, and cryptic codes to the user. Use trigger_error() after you used set_error_handler() to register your own callback function which either logs or emails the error codes to you, and echo a simple friendly message to the user.

And turn on a more verbose error handler function when you need to debug your scripts. In my init.php scripts I always have:

if (_DEBUG_) {
set_error_handler ('debug_error_handler');
}
else {
set_error_handler ('nice_error_handler');
}
up
10
richard at 2006 dot atterer dot net
18 years ago
Beware, trigger_error() is absolutely useless for transporting your own function's error messages in $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";

This outputs:

Error 1: ""
Error 2: "failed to open stream: No such file or directory"

This behaviour is consistent with the description of $php_errormsg, which says that the variable will only be available within the scope in which the error occurred. The problem can be worked around with a custom error handler like the one below. However, I'm undecided whether changing the language in this way is good:

function errHandler($errno, $errstr, $errfile, $errline) {
global $php_errormsg; $php_errormsg = $errstr;
}
set_error_handler('errHandler');
up
14
Howard Yeend
15 years ago
trigger_error always reports the line and file that trigger_error was called on. Which isn't very useful.

eg:

main.php:
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>

functions.php:
<?php
function doFunction($var) {
if(is_numeric($var)) {
/* do some stuff*/
} else {
trigger_error('var must be numeric');
}
}
?>

will output "Notice: var must be numeric in functions.php on line 6"
whereas "Notice: var must be numeric in main.php on line 4" would be more useful

here's a function to do that:

<?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);
}
?>

So now in our example:

main.php:
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>

functions.php:
<?php
function doFunction($var) {
if(is_numeric($var)) {
/* do some stuff*/
} else {
error('var must be numeric');
}
}

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);
}
?>

now outputs:

"Notice: var must be numeric in doFunction called from main.php on line 4"
up
4
PhpMyCoder
14 years ago
For those of you looking to use your own file or line number in the error (possibly using debug_backtrace()) instead of the ones created by trigger_error(), here is a solution:
Create a custom function to handle E_USER_ERRORs that simply outputs the error type and message, while excluding the line number and file trigger_error() reports. You may also configure it to handle user warnings and notices if necessary (I did in the example below).

<?php
function error_handler($level, $message, $file, $line, $context) {
//Handle user errors, warnings, and notices ourself
if($level === E_USER_ERROR || $level === E_USER_WARNING || $level === E_USER_NOTICE) {
echo '<strong>Error:</strong> '.$message;
return(true); //And prevent the PHP error handler from continuing
}
return(false); //Otherwise, use PHP's error handler
}

function trigger_my_error($message, $level) {
//Get the caller of the calling function and details about it
$callee = next(debug_backtrace());
//Trigger appropriate error
trigger_error($message.' in <strong>'.$callee['file'].'</strong> on line <strong>'.$callee['line'].'</strong>', $level);
}

//Use our custom handler
set_error_handler('error_handler');

//-------------------------------
//Demo usage:
//-------------------------------
function abc($str) {
if(!is_string($str)) {
trigger_my_error('abc() expects parameter 1 to be a string', E_USER_ERROR);
}
}

abc('Hello world!'); //Works
abc(18); //Error: abc() expects parameter 1 to be a string in [FILE].php on line 31
?>

This is a pretty simple concept and I'm sure most of you know this, but for those that don't, let it serve as a good example!
up
3
aydin dot kn12 at gmail dot com
10 years ago
If error_type is E_USER_ERROR then trigger_error throw FATAL ERROR and script stopped after this line.

<?php

$msg = 'This is the test message for echo';

trigger_error('Error message', E_USER_ERROR); // Script stopped after this line...

echo $msg; // This line does not appear...

?>
up
0
theking2 at king dot ma
4 months ago
The function trigger_error will terminate the script if $error_level is equal or higher than E_USER_ERROR.

If you write your own error handler you will have to do these yourself.

Example in which we assume the global LOG constant points to a PSR2 logging interface.
<?php

set_error_handler( function ($errno, $errstr, $errfile, $errline) {
// error was suppressed with the @-operator
if( 0 === error_reporting() ) {
return false;
}
switch($errno) {
default:
LOG->error( "Unknown error type: [$errno] $errstr", [ 'file' => $errfile, '@' => $errline ] );
exit(1);

case E_USER_ERROR: // fall through
case E_WARNING: // treat PHP warnings are errors
LOG->error( $errstr, [ 'file' => $errfile, '@' => $errline ] );
exit(1);

case E_USER_DEPRECATED:
case E_DEPRECATED:
LOG->error( "DEPRECATED $errstr", [ 'file' => $errfile, '@' => $errline ] );
break;

case E_USER_WARNING: // fall through
case E_NOTICE: // treat PHP notices are warnings
LOG->warning( $errstr, [ 'file' => $errfile, '@' => $errline ] );
break;

case E_USER_NOTICE:
LOG->notice( $errstr, [ 'file' => $errfile, '@' => $errline ] );
break;

case E_ERROR: // fall through
case E_RECOVERABLE_ERROR:
LOG->critical( $errstr, [ 'file' => $errfile, '@' => $errline ] );
exit(1);

}
/* Don't execute PHP internal error handler */
return true;
} );
?>
＋添加备注

备份地址：http://www.lvesu.com/blog/php/function.trigger-error.php