floatval()

Introdução

A função floatval() é uma função nativa do PHP que retorna o valor float (ponto flutuante) de uma variável. Você a utiliza sempre que tem um valor de tipo incerto — tipicamente uma string vinda de um formulário, query string, arquivo CSV ou payload JSON — e precisa garantir que está trabalhando com um número sobre o qual pode realizar operações aritméticas.

floatval() é um alias de doubleval(). O PHP não possui um tipo double separado — float e double são a mesma coisa — portanto, as duas funções são intercambiáveis; floatval() é a grafia que você deve preferir em código novo.

Esta página cobre a sintaxe, como a função interpreta diferentes entradas (incluindo a regra para strings que surpreende à primeira vista), como ela se compara ao cast (float), e as armadilhas que vale conhecer.

Sintaxe

float floatval(mixed $value)

Ela recebe um único argumento, $value, e retorna seu valor float. O argumento deve ser um escalar (string, int, float ou bool); passar um array retorna 1.0 para um array não vazio e 0.0 para um array vazio, e passar um object gera um erro.

Exemplo de Uso

O exemplo abaixo converte vários tipos diferentes e imprime o resultado. Note que floatval() retorna um float, mas quando o PHP imprime um float de número inteiro com echo ele omite o .0 final — portanto 42.0 é exibido como 42.

Aqui $var1 é uma string numérica, $var2 é um inteiro, $var3 é um boolean, e $var4 é uma string sem número no início. Cada um é convertido para float. Para confirmar que o resultado realmente é um float (em vez de depender do que o echo exibe), envolva o valor em var_dump(): var_dump(floatval(42)); imprime float(42).

Como strings são interpretadas

Esta é a parte que pega as pessoas de surpresa. Ao receber uma string, floatval() lê a parte numérica inicial e para no primeiro caractere que não pode fazer parte de um número. Ela não exige que toda a string seja numérica.

<?php
echo floatval("12.5abc") . "\n"; // 12.5  (stops at "a")
echo floatval("  7.0kg")  . "\n"; // 7     (leading whitespace is skipped)
echo floatval("1.0e3")    . "\n"; // 1000  (scientific notation is understood)
echo floatval("$199.99")  . "\n"; // 0     (starts with "$", no leading number)
echo floatval("0x1A")     . "\n"; // 0     (hex strings are NOT parsed)
echo floatval("")         . "\n"; // 0     (empty string)
?>

As regras principais:

• Espaços em branco no início são ignorados; a varredura começa no primeiro caractere que não seja espaço.
• Notação científica (1.0e3) e um sinal no início (-3.5, +2) são reconhecidos.
• A interpretação para no primeiro caractere não numérico, e tudo após ele é descartado.
• Se não houver número no início, o resultado é 0.0. Isso significa que uma string de moeda como "$199.99" resulta em 0, não em 199.99 — remova o símbolo antes.
• Strings hexadecimais como "0x1A" são tratadas como o número 0, pois a varredura para no x.

floatval() vs. o cast (float)

floatval($x) e (float) $x produzem o mesmo resultado para entradas escalares, portanto para um único valor o cast é mais curto:

<?php
$price = "49.95 USD";
echo floatval($price) . "\n"; // 49.95
echo (float) $price   . "\n"; // 49.95
?>

A vantagem de floatval() é que ela é uma função callable. Você pode passá-la diretamente para funções de ordem superior onde uma palavra-chave de cast não pode ser usada:

<?php
$inputs = ["1.5", "2.25", "x", "3"];
$floats = array_map('floatval', $inputs);
print_r($floats);
// Array ( [0] => 1.5 [1] => 2.25 [2] => 0 [3] => 3 )
?>

Se você precisar de validação estrita — rejeitando qualquer coisa que não seja um número limpo em vez de coagir silenciosamente — use is_numeric() ou filter_var($x, FILTER_VALIDATE_FLOAT) antes de converter, pois floatval() nunca reporta falha.

Quando usar

• Normalizar entrada do usuário ($_POST, $_GET) ou dados de CSV/texto antes de fazer cálculos.
• Como callback para array_map(), comparações com usort() e similares.
• Converter um valor cujo tipo você não controla em um float garantido.

Se você quiser um inteiro em vez disso, use intval(); para alterar o tipo de uma variável no lugar, use settype(); para verificar um tipo, use gettype() ou is_float(). Para uma visão geral de como o PHP lida com tipos, veja PHP Data Types.

Conclusão

floatval() retorna o valor float de qualquer escalar e nunca gera exceção com entrada inválida — volta a 0.0 em vez disso. Isso a torna conveniente, mas também significa que você deve validar primeiro quando um número ausente ou mal formado deve ser tratado como erro. Lembre-se da regra de string numérica inicial ("12.5abc" vira 12.5, "$199.99" vira 0), e prefira floatval() em vez do cast sempre que precisar passar a conversão como callback.

Prática