PHP: Hypertext Preprocessor (original) (raw)

trigger_error

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

trigger_error — Generates a user-level error/warning/notice message

Description

This function is useful when you need to generate a particular response to an exception at runtime.

Parameters

message

The designated error message for this error. It's limited to 1024 bytes in length. Any additional characters beyond 1024 bytes will be truncated.

error_level

The designated error type for this error. It only works with the [E_USER_*](errorfunc.constants.php#constant.e-user-error) family of constants, and will default to [E_USER_NOTICE](errorfunc.constants.php#constant.e-user-notice).

Return Values

Always returns [true](reserved.constants.php#constant.true).

Changelog

Version	Description
8.4.0	Passing E_USER_ERROR as theerror_level is now deprecated. Throw an Exception or call exit() instead.
8.4.0	The function now has a return type of true instead of bool.
8.0.0	The function now throws a ValueError if an invaliderror_level is specified. Previously, it returned false.

Examples

Example #1 trigger_error() example

See set_error_handler() for a more extensive example.

<?php <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>p</mi><mi>a</mi><mi>s</mi><mi>s</mi><mi>w</mi><mi>o</mi><mi>r</mi><mi>d</mi><mo>=</mo></mrow><annotation encoding="application/x-tex">password = </annotation></semantics></math>password=_POST['password'] ?? ''; if ($password === '') { trigger_error("Using an empty password is unsafe", E_USER_WARNING); } <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>h</mi><mi>a</mi><mi>s</mi><mi>h</mi><mo>=</mo><mi>p</mi><mi>a</mi><mi>s</mi><mi>s</mi><mi>w</mi><mi>o</mi><mi>r</mi><msub><mi>d</mi><mi>h</mi></msub><mi>a</mi><mi>s</mi><mi>h</mi><mo stretchy="false">(</mo></mrow><annotation encoding="application/x-tex">hash = password_hash(</annotation></semantics></math>hash=passwordhash(password, PASSWORD_DEFAULT); ?>

Notes

Warning

HTML entities in message are not escaped. Use htmlentities() on the message if the error is to be displayed in a browser.

Found A Problem?

someone at attbi dot com ¶

22 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');
}

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:

functions.php:

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:

'.$caller['function'].' called from '.$caller['file'].' on line '.$caller['line'].''."\n
error handler", $level); } ?>

So now in our example:

main.php:

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 '.$caller['function'].' called from '.$caller['file'].' on line '.$caller['line'].''."\n
error handler", $level);
}
?>

now outputs:

"Notice: var must be numeric in doFunction called from main.php on line 4"

richard at 2006 dot atterer dot net ¶

19 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,errstr, errstr,errfile, $errline) {
global phperrormsg;php_errormsg; phperrormsg;php_errormsg = $errstr;
}
set_error_handler('errHandler');

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.

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).

message,message, message,file, line,line, line,context) { //Handle user errors, warnings, and notices ourself if($level === E_USER_ERROR || level===EUSERWARNING∣∣level === E_USER_WARNING || level===EUSERWARNING∣∣level === E_USER_NOTICE) { echo 'Error: '.$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 '.$callee['file'].' on line '.$callee['line'].'', $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!

theking2 at king dot ma ¶

8 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,errstr, 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′=>errstr", [ 'file' => errstr",[′file′=>errfile, '@' => $errline ] );
exit(1);

case

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

case

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

case

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

case

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

case

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

}

/* Don't execute PHP internal error handler */
return true;
} );
?>

PHP: Hypertext Preprocessor (original) (raw)

trigger_error

Description

Parameters

Return Values

Changelog

Examples

Notes

See Also

Found A Problem?