localeconv()

A função PHP localeconv() retorna um array associativo que descreve como números e valores monetários devem ser formatados no locale atualmente ativo — qual separador decimal usar, qual separador de milhares, o símbolo da moeda, onde o símbolo e o sinal ficam, entre outros. Ela lê o locale definido mais recentemente com setlocale(), funcionando como uma ponte entre "em qual locale estou" e "quais são as regras de formatação."

Esta página abrange a sintaxe, cada chave do array retornado, um exemplo executável e o problema que afeta a maioria das pessoas: o locale padrão retorna valores em grande parte vazios.

Sintaxe

localeconv(): array

localeconv() não recebe nenhum argumento e sempre retorna um array. Ela não possui modo de falha — não há valor a ser passado e ela nunca retorna false.

Um exemplo básico

php— editable, runs on the server

Observe a chamada a setlocale() na primeira linha. Sem ela, o script é executado no locale padrão C, onde a maioria dos campos monetários retorna vazio — veja o problema descrito abaixo.

O array retornado

localeconv() retorna estas chaves. As chaves simples (decimal_point, thousands_sep) se aplicam a números comuns; as chaves mon_* se aplicam especificamente a valores monetários.

Chave	Significado
`decimal_point`	Separador decimal para números não monetários (ex.: `.`)
`thousands_sep`	Separador de milhares para números não monetários (ex.: `,`)
`grouping`	Array descrevendo o agrupamento de dígitos, ex.: `[3]` = grupos de 3
`int_curr_symbol`	Símbolo de moeda internacional, ex.: `USD`
`currency_symbol`	Símbolo de moeda local, ex.: `$`
`mon_decimal_point`	Separador decimal para valores monetários
`mon_thousands_sep`	Separador de milhares para valores monetários
`mon_grouping`	Agrupamento de dígitos para valores monetários
`positive_sign` / `negative_sign`	Strings de sinal para valores positivos / negativos
`int_frac_digits` / `frac_digits`	Número de dígitos fracionários (internacional / local)
`p_cs_precedes` / `n_cs_precedes`	`1` se o símbolo da moeda precede um valor positivo / negativo, `0` se vem depois
`p_sep_by_space` / `n_sep_by_space`	`1` se um espaço separa o símbolo do valor
`p_sign_posn` / `n_sign_posn`	Onde o sinal fica em relação ao valor e ao símbolo

Para inspecionar o array inteiro de uma vez, use print_r():

<?php
setlocale(LC_ALL, 'en_US.UTF-8');
print_r(localeconv());
?>

Para um sistema en_US.UTF-8, a saída (abreviada) é:

Array
(
    [decimal_point] => .
    [thousands_sep] => ,
    [int_curr_symbol] => USD
    [currency_symbol] => $
    [frac_digits] => 2
    [p_cs_precedes] => 1
    [grouping] => Array ( [0] => 3 )
    ...
)

Problema: o locale padrão retorna valores vazios

Antes de chamar localeconv(), o PHP é executado no locale C, a não ser que você defina um. No locale C, quase todos os campos monetários ficam vazios e os campos de contagem de dígitos retornam 127 (o marcador do padrão C para "valor não disponível"):

<?php
// No setlocale() — default C locale.
$info = localeconv();
var_dump($info['currency_symbol']);  // string(0) ""
var_dump($info['frac_digits']);      // int(127)
?>

Portanto, se localeconv() parece "não retornar nada útil," você quase certamente esqueceu de chamar setlocale() antes. Defina o locale explicitamente e esteja ciente de que os locales disponíveis dependem do sistema operacional em que o script é executado.

Quando eu usaria isso?

Raramente se chama localeconv() para formatar saídas manualmente — number_format() e a classe NumberFormatter da extensão intl fazem isso por você. É mais útil quando você precisa das regras brutas do locale, por exemplo para:

construir um formatador personalizado que respeite o locale do usuário,
normalizar a entrada do usuário (saber se 1.234,56 usa , ou . como separador decimal),
decidir se o símbolo da moeda vai antes ou depois do valor.

Funções relacionadas

setlocale() — define o locale que localeconv() lê.
number_format() — formata um número com agrupamento de milhares.
money_format() — formatação de moeda sensível ao locale (removida no PHP 8.0).
strftime() — formatação de data/hora sensível ao locale.

Prática

O que a função localeconv() do PHP faz?

Ela converte uma string de um locale para outro.Ela fornece informações sobre as regras de formatação numérica e monetária do locale atual.Ela define o locale para um novo valor com base no argumento especificado.Ela retorna um array associativo que contém informações sobre formatação numérica e monetária.