trigger_error
Raises a user-level error, warning, notice or deprecation that PHP's error handling picks up.
trigger_error(string $message, int $error_level = E_USER_NOTICE): true- Added in PHP 4.0.1
Parameters
| Parameter | Type | Description |
|---|---|---|
$message | string | The error message to report. Limited to 1024 bytes; anything longer is truncated. |
$error_leveloptional | int= E_USER_NOTICE | The error type to raise. Only the E_USER_* constants are accepted: E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE or E_USER_DEPRECATED. |
Return value
trueAlways returns true.
Errors
Throws a ValueError if error_level is not one of E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE or E_USER_DEPRECATED.
Changelog
- PHP 8.4Passing E_USER_ERROR as error_level is deprecated. Throw an Exception or call exit() instead.
- PHP 8.4The declared return type changed from bool to true.
- PHP 8.0An invalid error_level now throws a ValueError. Earlier versions just returned false, so bad calls failed silently.
trigger_error() pushes a message into the same pipeline that PHP's own warnings and notices travel through. It respects error_reporting, it goes to the error log or the output depending on display_errors, and — most usefully — it is routed to whatever callback you registered with set_error_handler().
When to reach for it
Use it when something is wrong but not fatal, and when you want the report to flow through the application's existing error plumbing rather than through your own logging call. The classic cases are deprecation notices for code you are phasing out, and validation warnings inside library code that should not decide for the caller whether to abort.
If the condition genuinely means the operation cannot continue, throw an exception instead. Exceptions carry a stack trace, can be typed, and can be caught. trigger_error() can only be intercepted by a global error handler, which makes it a poor fit for control flow.
What trips people up
Only the four E_USER_* constants are legal. Passing E_WARNING or E_DEPRECATED looks reasonable and throws a ValueError on PHP 8. Also note that a custom handler returning true swallows the error completely — PHP's internal handler never sees it, and nothing is written to the log unless you write it yourself.
Example
When to use it
- Warn callers that a legacy function still works but is scheduled for removal.
- Flag an invalid configuration value at boot so it reaches the error log instead of silently falling back to a default.
- Emit a diagnostic from library code and let the host application's set_error_handler() decide where it goes.
- Report a recoverable data problem in a batch job without aborting the whole run.
Frequently asked questions
What is the difference between trigger_error and throw?
throw raises an exception that unwinds the call stack and can be caught with try/catch, while trigger_error just reports a message and execution continues at the next statement. Use an exception when the operation cannot complete, and trigger_error when you only want to record that something looked wrong.
Why does trigger_error throw a ValueError?
Because error_level was not one of E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE or E_USER_DEPRECATED. Core constants such as E_WARNING and E_DEPRECATED are not accepted; before PHP 8.0 the call returned false instead of throwing, which is why old code often gets away with it.
Does trigger_error stop the script?
Only with E_USER_ERROR, and only when no custom error handler is installed — that combination ends the script immediately. Since PHP 8.4 passing E_USER_ERROR is deprecated, so throw an exception or call exit() when you actually need to halt.
More examples
Marking a function as deprecated
The call still returns its normal value — "1,234.50" — but a DEPRECATED line is emitted first. This is the polite way to retire an API: existing callers keep working, and their logs start telling them to migrate.
<?php
set_error_handler(function (int $no, string $msg): bool {
echo ($no === E_USER_DEPRECATED ? 'DEPRECATED' : 'OTHER') . ": $msg\n";
return true;
});
function oldFormat(float $n): string {
trigger_error('oldFormat() is deprecated, use number_format()', E_USER_DEPRECATED);
return number_format($n, 2);
}
echo oldFormat(1234.5), "\n";An invalid error level throws
E_WARNING is a core level, not a user level, so PHP 8 rejects it with a ValueError naming the four constants it will accept. The final line shows the successful call returning true, which since PHP 8.4 is the declared return type.
<?php
set_error_handler(fn() => true);
try {
trigger_error('this level is not allowed', E_WARNING);
} catch (ValueError $e) {
echo 'ValueError: ', $e->getMessage(), "\n";
}
var_dump(trigger_error('this level is allowed', E_USER_NOTICE));Routing user errors into your own log array
Both calls land in $log instead of the output stream, and the first one uses the default level, so its recorded level is E_USER_NOTICE (1024) while the second is E_USER_WARNING (512). restore_error_handler() puts the previous handler back so the rest of the script is unaffected.
<?php
$log = [];
set_error_handler(function (int $no, string $msg) use (&$log): bool {
$log[] = ['level' => $no, 'message' => $msg];
return true;
});
trigger_error('cache miss on user:42');
trigger_error('config key "timeout" missing', E_USER_WARNING);
restore_error_handler();
print_r($log);
Discussion