PHP user_error() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Error

Definition

In PHP, user_error() is an alias of trigger_error(). It creates your own error message at a level you choose, and it behaves exactly the same way.

An alias is just a second name for the same function. You can write user_error() or trigger_error() and get identical results. Most modern code uses trigger_error(), but you may see user_error() in older projects, so it is good to know that they are the same thing.

Syntax

Call user_error() with the values you need. Start with this line.

PHP
user_error("Something is wrong", E_USER_WARNING);
CallWhat it does
user_error("Cache is empty")Raises an E_USER_NOTICE, which is the default level.
user_error("Disk is almost full", E_USER_WARNING)Raises a user warning for a problem that needs attention.
user_error("Use newFunction() instead", E_USER_DEPRECATED)Tells developers that a feature is old.

user_error() and trigger_error() are the same function under two names. The level must be E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE or E_USER_DEPRECATED. Since PHP 8.4, E_USER_ERROR is deprecated.

Library declarations
PHP
user_error(string $message, int $error_level = E_USER_NOTICE): true

Parameters

ParameterDescription
messageRequired. The text of the error message. It is limited to 1024 bytes, and anything longer is cut off.
error_levelOptional. The error level. Use E_USER_NOTICE (the default), E_USER_WARNING, E_USER_DEPRECATED or E_USER_ERROR. Any other value throws a ValueError.

Return Value

Return ValueDescription
trueAlways returns true when the call succeeds.

PHP Examples

Example 1 — Using user_error()

A handler prints the level number and the message, so you can see user_error() working.

PHP
<?php
set_error_handler(function (int $errno, string $errstr): bool {
    echo "[", $errno, "] ", $errstr, PHP_EOL;
    return true;
});

user_error("Cache is empty");
user_error("Disk almost full", E_USER_WARNING);

How It Works

  1. set_error_handler() registers a function that prints the level number and message.
  2. user_error() with only a message uses the default level, E_USER_NOTICE, which is 1024.
  3. The second call passes E_USER_WARNING, which is 512.
  4. The handler returns true, so PHP does not print its own message.

Example 2 — Same Behavior as trigger_error()

Calling both names gives exactly the same kind of result, which shows that user_error() is only an alias.

PHP
<?php
$log = [];

set_error_handler(function (int $errno, string $errstr) use (&$log): bool {
    $log[] = $errno . ': ' . $errstr;
    return true;
});

trigger_error("From trigger_error", E_USER_WARNING);
user_error("From user_error", E_USER_WARNING);

foreach ($log as $line) {
    echo $line, PHP_EOL;
}

How It Works

  1. The handler stores each error as a line of text in the $log array.
  2. trigger_error() adds the first line, and user_error() adds the second.
  3. Both lines show the same level number, 512, because both calls used E_USER_WARNING.
  4. The two functions go through the same handler in the same way.

Example 3 — Marking Old Code as Deprecated

A common use is to warn developers that a function is old. E_USER_DEPRECATED is made for this.

PHP
<?php
set_error_handler(function (int $errno, string $errstr): bool {
    echo "Deprecated: ", $errstr, PHP_EOL;
    return true;
});

function oldFunction(): string {
    user_error("oldFunction() is deprecated, use newFunction()", E_USER_DEPRECATED);
    return "old result";
}

echo oldFunction(), PHP_EOL;

How It Works

  1. oldFunction() first raises a deprecation notice with user_error().
  2. The handler receives it and prints the message.
  3. The function does not stop, so it continues and returns its result.
  4. The echo prints old result after the deprecation message.

Frequently Asked Questions

It raises your own error at a level you choose, for example a notice, warning or deprecation. It is an alias of trigger_error().
Yes. They are the same function with two names, with the same parameters and the same behavior.
Use trigger_error() in new code. It is the name that most documentation and tutorials use, so other developers will recognize it more quickly.
E_USER_NOTICE (the default), E_USER_WARNING, E_USER_DEPRECATED and E_USER_ERROR. Other levels throw a ValueError, and E_USER_ERROR is deprecated since PHP 8.4.
It returns true when the call succeeds.

Back to Error Functions

Browse all PHP error function tutorials.

Error functions →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful