Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Exceptions and Errors

PHP trigger_error() function

Reference for PHP trigger_error() (alias user_error): raise E_USER_NOTICE, E_USER_WARNING, E_USER_ERROR or E_USER_DEPRECATED errors, with handlers and examples.

trigger_error() raises a user-level error from your own code. It goes through the same machinery as errors from PHP itself: error_reporting, display_errors, the log and any handler installed with set_error_handler() all apply. Its alias is user_error().

You choose the severity with one of four E_USER_* constants. Today the most common use is E_USER_DEPRECATED, which tells callers that a function will go away without breaking them. For failures that callers should handle, throw an exception instead.

PHP
trigger_error("oldFunction() is deprecated, use newFunction()", E_USER_DEPRECATED);

Try it

PHP The four user levels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Deprecating a function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
trigger_error(string $message, int $error_level = E_USER_NOTICE): true
user_error(string $message, int $error_level = E_USER_NOTICE): true
Name Description
$message The error text.
$error_level One of E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE (default) or E_USER_DEPRECATED.

Return value: true (the return type is true since PHP 8.2; bool before that).

Errors: a ValueError is thrown for any other level (PHP 8.0+); earlier versions returned false with a warning.

Usage notes

  • E_USER_ERROR is fatal when no handler deals with it: the script stops after the message. A handler that returns normally lets execution continue.
  • E_USER_ERROR is deprecated since PHP 8.4. Passing it raises a deprecation notice; throw an exception or call exit() with a message instead.
  • Not an exception. try/catch does not see these errors unless a handler throws. Prefer throw for conditions the caller must handle.
  • Deprecation pattern: trigger_error(__FUNCTION__ . '() is deprecated', E_USER_DEPRECATED); at the top of the old function. Production setups usually log these without displaying them.
  • The reported file and line are those of the trigger_error() call. Libraries sometimes want the caller's location; pass it in the message with debug_backtrace().
  • Respect the settings. error_reporting can hide a level, and @trigger_error() suppresses the message.
  • Avoid in new APIs. Modern code throws exceptions for errors and uses a logger for diagnostics.