intval()

Introdução

A função intval() retorna o valor inteiro de uma variável. É uma das funções de conversão de tipo do PHP, ao lado de floatval(), strval() e boolval(). Você usa intval() quando tem dados que parecem um número mas estão armazenados como string, float ou outro tipo — por exemplo, um valor proveniente de um formulário, um parâmetro de query de URL ou um arquivo CSV — e precisa de um inteiro real para contar, indexar ou fazer operações aritméticas.

Esta página aborda a assinatura da função, como o parâmetro opcional $base funciona, o que acontece com cada tipo de entrada e os erros comuns que pegam as pessoas de surpresa.

Sintaxe

intval(mixed $value, int $base = 10): int

Aceita até dois parâmetros e sempre retorna um int:

• $value — o valor a converter. Pode ser uma string, float, boolean, null ou array.
• $base (opcional) — a base numérica para interpretar $value. É usado apenas quando $value é uma string; é ignorado para qualquer outro tipo. O padrão é 10.

intval() nunca lança exceções e nunca retorna null. Se não conseguir encontrar um número para analisar, retorna 0.

Exemplo básico

Este é o caso mais comum — converter strings com aparência numérica em inteiros, incluindo bases não decimais:

O segundo argumento diz ao intval() como ler a string. "101010" na base 2 equivale ao decimal 42, e "2c" na base 16 equivale ao decimal 44. Uma string sem parte numérica inicial, como "not a number", produz 0.

Convertendo tipos não string

Quando você passa algo diferente de uma string, intval() segue as regras normais de conversão para inteiro do PHP e ignora $base:

<?php
echo intval(4.7) . "\n";    // 4    (floats are truncated, not rounded)
echo intval(true) . "\n";   // 1    (false → 0)
echo intval(null) . "\n";   // 0
echo intval([]) . "\n";     // 0    (empty array)
echo intval([0]) . "\n";    // 1    (non-empty array)
?>

Dois pontos importantes para lembrar:

• Floats são truncados em direção a zero, não arredondados. intval(4.7) é 4, e intval(-4.7) é -4. Se quiser arredondamento, use round() primeiro.
• Arrays convertem para 0 quando vazios e 1 quando não vazios — quase nunca é o que você quer, portanto não confie nisso.

Como as strings são analisadas

Para strings, intval() lê a parte numérica inicial e para no primeiro caractere que não consegue interpretar:

<?php
echo intval("12abc") . "\n";    // 12   (stops at "a")
echo intval("  123  ") . "\n";  // 123  (leading whitespace is skipped)
echo intval("abc12") . "\n";    // 0    (starts with a non-number)
?>

Detectando a base automaticamente com $base = 0

Se você definir $base como 0, intval() inspeciona o prefixo da string e escolhe a base automaticamente:

<?php
echo intval("0x1A", 0) . "\n";   // 26   (0x → hexadecimal)
echo intval("0b101", 0) . "\n";  // 5    (0b → binary)
echo intval("042", 0) . "\n";    // 34   (leading 0 → octal)
echo intval("42", 0) . "\n";     // 42   (no prefix → decimal)
?>

Isso é útil ao analisar valores de configuração que podem estar escritos em diferentes notações.

Armadilhas comuns

Literais octais vs. strings octais. Um zero inicial no código-fonte torna um número um literal octal antes mesmo que intval() seja executado, portanto intval(042) é 34 (porque 042 já é 34). Mas a string "042" é decimal 42 com a base padrão 10. Mantenha os números como strings se quiser uma análise previsível.

$base não faz nada para não strings. intval(255, 16) é 255, não 597 — a base é ignorada porque 255 já é um inteiro. Converta a partir de uma string se quiser reinterpretar os dígitos.

Valores fora do intervalo. Em uma plataforma de 64 bits, um valor maior que PHP_INT_MAX satura em PHP_INT_MAX em vez de causar overflow para um número negativo.

Quando usar intval() vs. alternativas

• Use intval() quando quiser uma conversão tolerante que retorna 0 em caso de falha e pode ler outras bases.
• Use a conversão (int) ((int)$value) para uma conversão rápida apenas em decimal; ela se comporta como intval() com base 10.
• Use filter_var($value, FILTER_VALIDATE_INT) quando precisar de validação — retorna false para entradas não inteiras em vez de silenciosamente devolver 0, para que você possa distinguir um 0 real de uma falha de análise.

Conclusão

intval() converte strings, floats, booleans e outros valores para inteiro, com uma base opcional para analisar strings em binário, octal, hexadecimal ou qualquer base de 2 a 36. Seu comportamento tolerante — retornando 0 em caso de falha e truncando floats — torna-o conveniente, mas essa mesma tolerância pode ocultar entradas inválidas, portanto prefira filter_var() quando precisar realmente validar. Para as conversões relacionadas, consulte floatval(), strval() e gettype().

Prática