hexdec()

A função hexdec() do PHP converte uma string hexadecimal (base 16) em seu equivalente decimal (base 10). É o inverso de dechex() e é muito útil quando você precisa ler valores hexadecimais provenientes de cores, dumps de bytes, hashes ou protocolos de baixo nível e precisa realizar operações aritméticas com eles.

Esta página abrange a sintaxe, o que o tipo de retorno realmente é, como hexdec() lida com caracteres inválidos, o problema com números grandes e como ela se relaciona com as outras funções de conversão de base.

Sintaxe

hexdec(string $hex_string): int|float

• $hex_string — a string hexadecimal a ser convertida. Os dígitos hexadecimais são 0-9 e a-f (sem distinção entre maiúsculas e minúsculas, portanto FF e ff são iguais).
• Valor de retorno — o valor decimal como int, ou um float quando o número é grande demais para caber em um inteiro PHP.

Um Exemplo Básico

1a em base 16 significa 1 × 16 + 10 = 26, que é o valor impresso. A entrada é uma string aqui — essa é a forma normal e recomendada de passar valores hexadecimais, pois um literal como 1a não é um PHP válido e 0x1a já seria um inteiro.

Convertendo Vários Valores

hexdec() não faz distinção entre maiúsculas e minúsculas e ignora qualquer prefixo 0x que você possa copiar de outra ferramenta:

<?php
echo hexdec("ff"), "\n";   // 255
echo hexdec("FF"), "\n";   // 255 (same — case does not matter)
echo hexdec("100"), "\n";  // 256
echo hexdec("7fff"), "\n"; // 32767
echo hexdec("0x1A"), "\n"; // 26  (the "0x" is ignored)
?>

Um uso prático comum é dividir uma cor CSS em hexadecimal nos seus canais vermelho, verde e azul:

<?php
$color = "ff8800";

$red   = hexdec(substr($color, 0, 2)); // 255
$green = hexdec(substr($color, 2, 2)); // 136
$blue  = hexdec(substr($color, 4, 2)); // 0

echo "rgb($red, $green, $blue)"; // rgb(255, 136, 0)
?>

Como os Caracteres Inválidos São Tratados

hexdec() não lança um erro em uma string malformada. Em vez disso, todo caractere que não seja um dígito hexadecimal válido é silenciosamente ignorado (e, desde o PHP 7.4, um aviso de depreciação/E_WARNING é emitido). Os dígitos válidos restantes ainda são convertidos:

<?php
echo hexdec("a0.5"), "\n"; // 2565 — the "." is dropped, so "a05" is converted
echo hexdec("xyz1f"), "\n"; // 31  — only "1f" is valid hex
?>

Como a falha é silenciosa, valide a entrada você mesmo quando ela puder ser não confiável. ctype_xdigit() verifica se uma string contém apenas dígitos hexadecimais:

<?php
$input = "a0.5";

if (ctype_xdigit($input)) {
    echo hexdec($input);
} else {
    echo "Not a valid hexadecimal string";
}
// Not a valid hexadecimal string
?>

Números Grandes Retornam um Float

Os inteiros do PHP são limitados pela plataforma (64 bits na maioria dos sistemas modernos). Quando um valor hexadecimal excede PHP_INT_MAX, hexdec() retorna um float em vez de um int para que o valor não seja truncado — embora floats muito grandes percam precisão:

<?php
var_dump(hexdec("1a"));               // int(26)
var_dump(hexdec("ffffffffffffffff")); // float(1.8446744073709552E+19)
?>

Se você precisar de aritmética exata com números hexadecimais enormes, use as extensões BCMath ou GMP.

Funções Relacionadas de Conversão de Base

hexdec() faz parte de uma família de conversores de base. Escolha a que corresponde às suas bases de entrada e saída:

Para bases arbitrárias (qualquer base de 2 a 36) use base_convert(), e para converter uma string hexadecimal em bytes brutos use hex2bin().

Conclusão

hexdec() converte uma string hexadecimal em um número decimal, retornando um int (ou um float para valores muito grandes). Lembre-se de que ela ignora caracteres inválidos silenciosamente — portanto valide entradas não confiáveis com ctype_xdigit() primeiro — e use sua função inversa dechex() para converter de volta.

Prática