trigger_error()

Introduction

trigger_error() lets your own code raise a PHP error message the same way the engine raises built-in ones. It is the standard way to signal that a function was called incorrectly — a missing argument, an out-of-range value, a deprecated call — without throwing an exception or printing an ad-hoc echo. Because the message flows through PHP's normal error pipeline, it respects error_reporting, can be logged automatically, and can be intercepted by a custom error handler.

This page explains what trigger_error() does, its syntax and error levels, and shows a runnable example for each level plus a practical input-validation use case.

What is the trigger_error() function?

trigger_error() raises a user-level error — an error your program generates on purpose, as opposed to one the PHP engine raises on its own. When you call it, PHP behaves exactly as if it had hit that error itself: it applies the current error_reporting mask, sends the message to the active error handler (or the default one), and may halt the script depending on the level.

Two things are easy to get wrong:

• trigger_error() raises an error, not an exception. It will not be caught by try/catch unless a custom handler converts it into an exception (a common pattern shown below).
• The function always returns false, so return trigger_error(...) is rarely what you want.

Syntax of trigger_error()

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

The error level must be one of:

• E_USER_ERROR — a fatal error. With the default handler it stops the script immediately. With a custom handler the script continues unless the handler stops it (returns false and lets PHP fall through, or calls exit()).
• E_USER_WARNING — a non-fatal warning. The script keeps running.
• E_USER_NOTICE — an informational message. The script keeps running. This is the default.

Passing any other constant (for example E_WARNING) raises an E_USER_WARNING of its own and ignores your value.

trigger_error() honors the current error_reporting level: if the triggered level is masked off, nothing is reported. So if error_reporting(E_ALL & ~E_USER_NOTICE) is set, a notice you trigger is silently dropped.

Heads-up for PHP 8.4+: triggering E_USER_ERROR is deprecated. Throwing an exception is now the recommended way to signal a fatal user-level condition. The other two levels remain fully supported.

A simple notice with the default handler

The minimal use of trigger_error() is a single call. With PHP's default error handler and display enabled, it prints a formatted line and execution continues (notices are non-fatal):

<?php
echo "Before\n";
trigger_error("Something worth noting", E_USER_NOTICE);
echo "After\n";

Output (with display_errors on):

Before

Notice: Something worth noting in /path/to/script.php on line 3
After

The script reaches the final echo because a notice does not stop execution.

Telling the levels apart with a custom handler

A custom error handler gives you full control over how each level is rendered. The handler receives the level number as $errno, so you can map it to a label and decide what to do next.

<?php
function custom_error_handler($errno, $errstr, $errfile, $errline) {
  $label = match ($errno) {
    E_USER_ERROR   => 'ERROR',
    E_USER_WARNING => 'WARNING',
    E_USER_NOTICE  => 'NOTICE',
    default        => 'UNKNOWN',
  };
  echo "[$label] $errstr (line $errline)\n";
  // Returning true tells PHP we handled it, so the default handler is skipped.
  return true;
}

set_error_handler("custom_error_handler");

trigger_error("Disk is almost full", E_USER_NOTICE);
trigger_error("Cache miss, falling back to DB", E_USER_WARNING);

echo "Script finished\n";

Output:

[NOTICE] Disk is almost full (line 16)
[WARNING] Cache miss, falling back to DB (line 17)
Script finished

The handler returns true, telling PHP the error was handled, so the default handler is skipped and the script continues. The E_USER_ERROR arm is kept in the match for completeness, but note that with the default handler an E_USER_ERROR would stop the script before "Script finished" — and on PHP 8.4+ triggering that level is deprecated.

Practical use: validating function arguments

The most common real-world use of trigger_error() is guarding a function against bad input — emitting a warning when a caller passes something invalid, then returning a safe default:

<?php
function divide($a, $b) {
  if ($b == 0) {
    trigger_error("divide(): division by zero, returning 0", E_USER_WARNING);
    return 0;
  }
  return $a / $b;
}

echo divide(10, 2), "\n";   // 5
echo divide(10, 0), "\n";   // warning + 0

Output (with display_errors on):

5

Warning: divide(): division by zero, returning 0 in /path/to/script.php on line 4
0

This pattern keeps the caller's stack trace and line number in the message, which makes it far easier to find the offending call than a bare echo.

Converting errors into exceptions

If you prefer to handle problems with try/catch, a custom handler can turn a triggered error into an ErrorException. This is the bridge between PHP's error system and its exception system:

<?php
set_error_handler(function ($errno, $errstr, $errfile, $errline) {
  throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

try {
  trigger_error("Recoverable problem", E_USER_WARNING);
} catch (ErrorException $e) {
  echo "Caught: " . $e->getMessage() . "\n";
}

Output:

Caught: Recoverable problem

Because the handler throws, the warning never reaches the default error output — it is delivered to your catch block instead.

Common pitfalls

• It is not an exception. Without a handler that throws, try/catch will not catch a triggered error.
• error_reporting can hide it. If the level is masked off, your message vanishes with no indication. Check the current level with error_reporting().
• E_USER_ERROR is deprecated in PHP 8.4+. Throw an exception (or call die()) for fatal user-level conditions instead.
• The message is truncated at 1024 bytes — keep it concise.

Conclusion

trigger_error() is the idiomatic way to raise a user-level E_USER_NOTICE, E_USER_WARNING, or (legacy) E_USER_ERROR. It plugs your messages into PHP's standard pipeline so they respect error_reporting, can be logged, and can be intercepted by a custom error handler — or converted into exceptions when you want try/catch semantics. For new fatal-level code, prefer throwing exceptions over E_USER_ERROR.

Practice