trigger_error

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

trigger_error — Déclenche une erreur utilisateur

Description

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

trigger_error() est utilisé pour déclencher une erreur utilisateur. Elle peut aussi être utilisée en conjonction avec un gestionnaire d'erreurs interne, ou un gestionnaire d'erreurs utilisateur qui a été choisi comme gestionnaire d'erreurs avec set_error_handler().

trigger_error() est pratique lorsque vous devez générer une réponse particulière lors de l'exécution.

Liste de paramètres

message: Le message d'erreur désigné pour cette erreur. Il est limité en longueur à 1024 octets. Tous caractères après les 1024 octets seront ignorés.
error_level: Le type d'erreur désigné pour cette erreur. Cela ne fonctionne qu'avec la famille de constantes E_USER_* et sera par défaut E_USER_NOTICE.

Avertissement
Passer E_USER_ERROR comme error_level est désormais obsolète. Lancez une Exception ou appelez exit() à la place.

Valeurs de retour

Retourne toujours true.

Erreurs / Exceptions

Cette fonction lance une ValueError si le error_level n'est pas l'un des E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE, E_USER_DEPRECATED.

Historique

Version	Description
8.4.0	Passer `E_USER_ERROR` comme `error_level` est désormais obsolète. Lancez une Exception ou appelez exit() à la place.
8.4.0	La fonction a désormais un type de retour true au lieu de bool.
8.0.0	La fonction lance désormais une ValueError si un `error_level` invalide est spécifié. Auparavant, elle retournait `false`.

Exemples

Exemple #1 Exemple avec trigger_error()

Voir set_error_handler() pour un exemple plus conséquent.

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

Notes

Avertissement

Les entités HTML contenues dans le paramètre message ne sont pas échappées. Utilisez la fonction htmlentities() sur le message si l'erreur doit être affichée dans un navigateur.

Voir aussi

error_reporting() - Fixe le niveau de rapport d'erreurs PHP
set_error_handler() - Spécifie une fonction utilisateur comme gestionnaire d'erreurs
restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
Les constantes de niveau d'erreur
L’attribut Deprecated

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