Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Exceptions and Errors

The PHP ValueError class

Reference for PHP ValueError: thrown when an argument has the right type but an unacceptable value, such as empty arrays, negative counts or unknown enum cases.

ValueError is an Error thrown when an argument has the correct type but its value is not acceptable. It was added in PHP 8.0, when many built-in functions stopped returning false or emitting warnings for bad values and started throwing instead.

Compare it with TypeError: str_repeat("ab", "x") is a type problem, while str_repeat("ab", -1) passes an integer, as required, that happens to be out of range. A ValueError means "this value can never work", so it is a bug to fix or an input to validate before the call.

PHP
try {
    array_combine(["a", "b"], [1]);
} catch (ValueError $e) {
    echo $e->getMessage();
}

Try it

PHP Built-in functions that throw ValueError

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 Throwing and handling it yourself

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
class ValueError extends Error {}

It adds nothing to Error; read the problem with getMessage(). Built-in messages follow the pattern function(): Argument #N ($name) must be ..., which names the parameter.

Common sources: array_combine() with arrays of different lengths, array_chunk() or str_split() with a size below 1, range() with a zero step, str_repeat() with a negative count, random_int() with min above max, max() and min() on an empty array, array_rand() on an empty array, string offsets out of range in strpos() and friends, json_decode() with a bad depth, settype() with an unknown type name, backed enum from() with a value that has no case, mb_* functions given an unknown encoding.

Usage notes

  • Prevention beats catching. Check the value first ($whole > 0, $list !== []) or use a non-throwing variant such as tryFrom() on backed enums, which returns null instead.
  • Use it for your own functions when an argument has the right type but a bad value. It signals a programmer error, matching the built-ins; for user-facing validation failures prefer InvalidArgumentException or a custom exception.
  • ValueError is an Error, not an Exception, so catch (Exception $e) does not see it. Catch it by name or through Throwable.
  • Before PHP 8.0 most of these cases returned false and raised a warning. Code that checked the return value with === false needs a try/catch or a prior check on PHP 8+.
  • Not for external data. Input from users, files or APIs should be validated and reported to the user without relying on a thrown engine error.
  • Match on the class, not on the message text, which can change between versions.
  • Different from DomainException and RangeException, the SPL exceptions for domain and range violations in application code; those extend Exception.