Home/ Manual/ errorfunc / functions/ trigger_error

trigger_error

PHP function Edit on GitHub ✎

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

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

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

trigger_error() example

See set_error_handler() for a more extensive example.

php

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