dechex()

Purpose

dechex() converts an integer into a string of hexadecimal digits. Hexadecimal is base 16, with the digits 0-9 followed by a-f. It is common for colour codes, byte values, bit masks, identifiers and debugging output, because each hex digit maps neatly to four bits.

The function lives in the maths group and does one job: it takes a PHP int and gives back its base-16 text form. It does not add a 0x prefix, it does not pad the result, and it always uses lowercase letters.

Signature

Parameters and defaults

$num is the only parameter and it has no default. It is the decimal integer to convert.

The manual explains that PHP's int type is signed, while dechex() works with unsigned values. A negative integer is therefore treated as if it were unsigned. The largest value that can be represented is PHP_INT_MAX * 2 + 1, which is the same bit pattern as -1. The number of hex digits for such values depends on the platform's integer width: on a 32-bit build, -1 gives ffffffff, and on a 64-bit build the result is longer. Because of this, avoid printing negative conversions in code that must behave identically everywhere.

Since the parameter is typed int, a non-numeric string such as "abc" raises a TypeError. Numeric strings follow PHP's normal type juggling rules, depending on whether strict_types is enabled.

Return value and failure cases

The function returns a string containing the hexadecimal digits of $num, with no leading zeros except for the value zero itself, which gives "0". There is no false return and no warning for ordinary integers. The only failure you will normally meet is a TypeError caused by an argument that cannot be used as an integer.

Example 1: basic conversion

Small values show the lowercase output and the lack of any prefix.

<?php
echo dechex(10) . "\n";
echo dechex(47) . "\n";
echo dechex(255) . "\n";

a
2f
ff

Example 2: building a colour code

A byte value from 0 to 255 needs exactly two hex digits. dechex(15) returns only f, so pad each channel with str_pad() before joining them.

<?php
function rgbToHex(int $r, int $g, int $b): string
{
    $parts = [$r, $g, $b];
    $hex = '#';
    foreach ($parts as $part) {
        $hex .= str_pad(dechex($part), 2, '0', STR_PAD_LEFT);
    }
    return $hex;
}

echo json_encode([rgbToHex(255, 128, 0), rgbToHex(0, 15, 16)]) . "\n";

["#ff8000","#000f10"]

Example 3: uppercase, zero and round trip

If you need uppercase digits, wrap the result in strtoupper(). The inverse function hexdec() turns the string back into a number.

<?php
$value = 48879;
$result = [
    'upper' => strtoupper(dechex($value)),
    'zero' => dechex(0),
    'roundTrip' => hexdec(dechex($value)),
];
echo json_encode($result) . "\n";

{"upper":"BEEF","zero":"0","roundTrip":48879}

Edge cases

• Zero returns "0", a single digit, not an empty string.
• Negative numbers are interpreted as unsigned, so the output is a long string of f and other digits whose length depends on the integer size of the PHP build.
• Leading zeros are never produced. If a fixed width matters, such as two digits per byte or eight digits per 32-bit word, you must pad the string yourself.
• Return type is a string, so dechex(10) === "a". Comparing it with the number 10 using strict equality is false.
• Large values are limited by int. If you need to convert numbers beyond the integer range, dechex() is not the right tool.

Common mistakes

1. Expecting padding. Writing '#' . dechex($r) . dechex($g) . dechex($b) produces colour codes of the wrong length whenever a channel is below 16.
2. Expecting a prefix. The result is ff, not 0xff. Add the prefix yourself if your format needs it.
3. Assuming uppercase. The digits a to f are lowercase. Compare hex strings case-insensitively, or normalise them with strtolower() or strtoupper().
4. Relying on negative output. The length of the result for negative input is platform dependent, so tests that hard-code it can fail on a different build.
5. Confusing it with hexdec(). dechex() goes from number to hex string. hexdec() goes the other way.

Related functions

• hexdec() converts a hexadecimal string back to a decimal number.
• decbin() converts a decimal integer to a binary string.
• decoct() converts a decimal integer to an octal string.
• base_convert() converts a number between arbitrary bases, working on strings.
• str_pad() and sprintf() help produce fixed-width hex output.

Recap

dechex(int $num): string returns the lowercase base-16 form of an integer, treating negative values as unsigned. It adds no prefix and no padding, returns "0" for zero, and throws a TypeError for arguments that are not usable as integers. Pad with str_pad() when you need fixed width, and use strtoupper() when you need capital letters.