Função array_combine() do PHP

A função array_combine() do PHP mescla dois arrays simples em um único array associativo: ela utiliza os valores do primeiro array como chaves e os valores do segundo array como valores. É a ferramenta ideal quando você tem dois arrays paralelos — por exemplo, uma lista de nomes de colunas e uma lista de valores de células alinhados posição a posição — e deseja combiná-los em um único mapa de chave/valor.

Esta página cobre a sintaxe, o significado de cada parâmetro e do valor de retorno, as regras que você deve seguir (comprimento igual, tipos de chave válidos) e os padrões mais comuns no mundo real.

Sintaxe

array_combine(array $keys, array $values): array

Valor de retorno: um novo array associativo construído emparelhando cada elemento de $keys com o elemento de $values na mesma posição.

Desde o PHP 8.0, passar arrays de tamanhos diferentes lança um ValueError. No PHP 7.x e versões anteriores, a função retornava false e emitia um aviso.

Uso básico

O caso de uso clássico é transformar dois arrays paralelos em um mapa — aqui, nomes de produtos emparelhados com seus preços.

Isso irá exibir:

Array
(
    [Product 1] => 10
    [Product 2] => 20
    [Product 3] => 30
)

A combinação é feita por posição, não por ordenação ou correspondência — a primeira chave é emparelhada com o primeiro valor, a segunda com o segundo, e assim por diante.

Construindo uma linha a partir de cabeçalhos e dados

Um uso prático frequente é reconstruir um registro associativo a partir de uma linha de cabeçalho no estilo CSV mais uma linha de dados. É exatamente assim que você mapearia uma linha de um arquivo CSV analisado.

<?php

$headers = array("id", "name", "email");
$row     = array(101, "Ann", "[email protected]");

$record = array_combine($headers, $row);

echo $record["name"] . " <" . $record["email"] . ">";

Isso exibe:

Ann <[email protected]>

Regras e armadilhas

Tenha em mente estas restrições:

• Comprimento igual é obrigatório. $keys e $values devem ter o mesmo número de elementos. No PHP 8+, uma incompatibilidade lança um ValueError; proteja-se com count($keys) === count($values) se os comprimentos não forem conhecidos de antemão.
• As chaves devem ser válidas. Os valores usados como chaves devem ser inteiros ou strings. Floats são truncados para inteiros, booleans são convertidos para 0/1, e null se torna a string vazia "".
• Chaves duplicadas sobrescrevem. Se o array $keys contiver valores repetidos, os pares posteriores sobrescrevem os anteriores, de modo que o resultado pode ser menor que a entrada. Para obter primeiro a contagem de chaves únicas, consulte array_unique().
• Somente os valores são usados. As chaves originais de ambos os arrays de entrada são ignoradas — apenas seus valores importam.

O exemplo abaixo mostra uma chave duplicada colapsando duas entradas em uma:

<?php

$keys   = array("a", "b", "a");
$values = array(1, 2, 3);

print_r(array_combine($keys, $values));

O último "a" => 3 sobrescreve o primeiro, portanto a saída é:

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

Funções relacionadas

• array_merge() — une arrays acrescentando valores em vez de emparelhar chaves com valores.
• array_flip() — troca as chaves e os valores de um único array.
• array_keys() e array_values() — a operação inversa: extrai as chaves ou os valores de um array associativo.

Conclusão

array_combine() é a forma mais limpa de combinar dois arrays paralelos em um array associativo, emparelhando-os elemento a elemento. Lembre-se das duas regras que mais pegam as pessoas de surpresa: os arrays devem ter o mesmo comprimento (caso contrário, um ValueError no PHP 8+) e chaves duplicadas se sobrescrevem silenciosamente.

Prática