hexdec()

Purpose

hexdec() reads a string of hexadecimal digits and returns the number it represents. Hexadecimal (base 16) uses the digits 0-9 and the letters a-f. You will meet it when working with colour codes, byte values, hash fragments, memory-style identifiers and protocol constants written in hex.

Signature

Parameters and defaults

$hex_string is the only parameter and it has no default. It should contain only hexadecimal digits. Upper-case and lower-case letters are treated the same, so "FF" and "ff" give the same result. Leading zeros are harmless.

Return value

The function returns the decimal value as an int when it fits into the platform integer type. If the number is too large, the result is returned as a float instead. On a 64-bit build, PHP_INT_MAX is 7fffffffffffffff in hex, so one more than that already becomes a float. A float at this size can lose precision, so do not treat it as an exact integer.

Failure cases

hexdec() does not throw an exception for bad input. Instead, it ignores every character that is not a hexadecimal digit and computes the result from the remaining characters. Since PHP 7.4.0, passing invalid characters also raises a deprecation notice. This means hexdec("See") computes the value of "ee", which is 238, and hexdec("that") computes the value of "a", which is 10. An empty string simply produces 0.

Example 1: basic conversion

<?php
var_dump(hexdec("ee"));
var_dump(hexdec("a0"));

int(238)
int(160)

Both calls return integers. ee is 14 × 16 + 14 = 238, and a0 is 10 × 16 = 160.

Example 2: reading a colour code

A CSS colour such as #1e90ff stores three bytes. Remove the # yourself, split the rest into two-character pairs, and convert each pair.

<?php
$color = "#1e90ff";
$pairs = str_split(ltrim($color, "#"), 2);
$rgb = array_map('hexdec', $pairs);
echo json_encode($rgb), "\n";

[30,144,255]

Removing the # first matters, because the hash sign is not a hexadecimal digit and would trigger the deprecation notice.

Example 3: integer limits

The next example shows where the result switches from int to float.

<?php
$result = [
    'max' => hexdec("7fffffffffffffff") === PHP_INT_MAX,
    'overflowIsFloat' => is_float(hexdec("8000000000000000")),
];
echo json_encode($result), "\n";

{"max":true,"overflowIsFloat":true}

This assumes the 64-bit integer size used by the PHP 8.4 runtime for these lessons.

Edge cases

• Empty string: returns 0.
• Leading zeros: "000ff" is the same as "ff".
• Mixed case: "aB" and "Ab" are both 171.
• Very long strings: the result becomes a float, and low-order digits may no longer be represented exactly.
• Signs, spaces and separators: a minus sign, a space or a colon is an invalid character. It is skipped, so "-ff" does not produce a negative number; it is treated as "ff".
• Only invalid characters: the result is 0, after the deprecation notice.

Common mistakes

1. Expecting validation. hexdec() is forgiving, which can hide bad data. If the input comes from a user, validate it first, for example with ctype_xdigit(), and reject anything that is not purely hexadecimal.
2. Passing decorated strings. Values like #ff8800 or strings containing spaces should be cleaned before conversion. Do not rely on the function silently dropping characters, since that behaviour is deprecated.
3. Assuming negatives work. A leading - does not negate the value. Handle the sign in your own code and convert only the digits.
4. Ignoring float results. Large hex strings such as 64-bit hashes cannot be stored exactly after conversion. Keep them as strings if you need every digit.
5. Mixing up direction. hexdec() goes from hex to decimal. The opposite operation is dechex().

Related functions

• dechex() converts a decimal number to a hexadecimal string.
• bindec() converts a binary string to decimal.
• octdec() converts an octal string to decimal.
• base_convert() converts between arbitrary bases from 2 to 36, working on strings.
• ctype_xdigit() checks whether a string consists only of hexadecimal digits.

Recap

hexdec() converts a hexadecimal string to an int, or to a float when the value is too large for an integer. It is case-insensitive and returns 0 for an empty string. It skips invalid characters and, since PHP 7.4.0, reports them with a deprecation notice. Clean or validate input before calling it, and be careful with values that exceed the integer range.