trigger_error

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

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

Description

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

Used to trigger a user error condition, it can be used in conjunction with the built-in error handler, or with a user defined function that has been set as the new error handler (set_error_handler()).

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_* family of constants, and will default to E_USER_NOTICE.

Warning
Passing E_USER_ERROR as the error_level is now deprecated. Throw an Exception or call exit() instead.

Return Values

Always returns true.

Errors/Exceptions

This function throws a ValueError if error_level is not one of E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE, E_USER_DEPRECATED.

Changelog

Version	Description
8.4.0	Passing `E_USER_ERROR` as the `error_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 invalid `error_level` is specified. Previously, it returned `false`.

Examples

Example #1 trigger_error() example

See set_error_handler() for a more extensive example.

<?php
$password = $_POST['password'] ?? '';
if ($password === '') {
  trigger_error("Using an empty password is unsafe", E_USER_WARNING);
}
$hash = password_hash($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?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 6 notes

down

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

}

down

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

down

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"

down

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!

down

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

?>

down

theking2 at king dot ma ¶

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

＋add a note

trigger_error

Description

Parameters

Return Values

Errors/Exceptions

Changelog

Examples

Notes

See Also

Found A Problem?

User Contributed Notes 6 notes