Entendendo a Função PHP "array_count_values"

A função PHP array_count_values() conta quantas vezes cada valor aparece em um array. Ela retorna um novo array associativo no qual as chaves são os valores distintos do array de entrada e os valores indicam quantas vezes cada um ocorreu. É a maneira mais rápida de construir uma tabela de frequências (um histograma de valores) sem precisar escrever um loop manualmente.

Este capítulo aborda a sintaxe, as regras sobre quais valores podem ser contados, armadilhas comuns e receitas práticas, como encontrar o elemento mais frequente.

Sintaxe

array_count_values(array $array): array

A função retorna um array associativo de pares valor => contagem. Ela não modifica o array original.

Exemplo básico

Passe um array de valores e você receberá de volta cada valor distinto emparelhado com sua contagem:

Saída:

Array
(
    [red] => 2
    [green] => 1
    [blue] => 2
    [yellow] => 1
)

"red" e "blue" aparecem duas vezes cada, enquanto "green" e "yellow" aparecem uma vez. As chaves do array original são completamente ignoradas — apenas os valores importam.

Como chaves inteiras e string interagem

Como as chaves de array em PHP só podem ser inteiros ou strings, array_count_values() conta apenas valores int e string. Há uma consequência sutil: uma string numérica como "1" e o inteiro 1 são tratados como a mesma chave, portanto são contados juntos.

<?php

$mixed = array(1, "1", 1, "hello", "hello");
print_r(array_count_values($mixed));

?>

Saída:

Array
(
    [1] => 3
    [hello] => 2
)

O inteiro 1 e a string "1" são fundidos em uma única chave 1 com contagem 3. Isso reflete como o PHP normaliza chaves de array em todo lugar.

Valores que não podem ser contados

Qualquer valor que não seja int ou string — null, booleanos, floats, arrays ou objects — não pode ser usado como chave. O PHP o ignora e emite um aviso em vez de contá-lo:

<?php

$values = array("a", "b", null, 3.5, "a");
print_r(@array_count_values($values));

?>

Saída:

Array
(
    [a] => 2
    [b] => 1
)

Apenas os valores string são contados; null e o float 3.5 são descartados (a chamada real emite avisos "Can only count string and integer values" — o @ acima serve apenas para manter a saída limpa na demonstração). Faça a conversão de tipo ou filtre seus dados primeiro se precisar contar outros tipos.

Receita prática: encontrar o valor mais frequente

Uma tabela de frequências torna trivial encontrar a moda (o elemento mais comum). Ordene as contagens em ordem decrescente e leia a primeira chave:

<?php

$votes = array("yes", "no", "yes", "yes", "no", "maybe");
$counts = array_count_values($votes);
arsort($counts);            // sort by count, highest first, keeping keys
$winner = array_key_first($counts);

echo "Winner: $winner ({$counts[$winner]} votes)";

?>

Saída:

Winner: yes (3 votes)

Você também pode passar o resultado diretamente para array_sum() para confirmar o total, ou para max() para obter a contagem mais alta.

Contando palavras em uma string

Um caso de uso comum é construir um mapa de frequência de palavras. Divida a string em palavras com explode() e depois conte:

<?php

$text = "the cat sat on the mat the cat ran";
$words = explode(" ", $text);
print_r(array_count_values($words));

?>

Saída:

Array
(
    [the] => 3
    [cat] => 2
    [sat] => 1
    [on] => 1
    [mat] => 1
    [ran] => 1
)

Quando usar

Use array_count_values() sempre que precisar de um histograma de valores: contar votos, encontrar duplicatas, construir nuvens de tags ou detectar as entradas mais/menos comuns. É mais rápido e mais claro do que um loop foreach manual com verificações isset(), e elimina uma fonte frequente de erros de contagem.

Funções relacionadas

• array_unique() — remove valores duplicados (quando você se importa apenas com quais valores existem, não quantas vezes).
• array_keys() — extrai apenas os valores distintos uma vez que eles sejam chaves.
• array_sum() — totaliza as contagens.
• arsort() — ordena a tabela de frequências resultante por contagem.

Prática