Entendendo a Função PHP: array_intersect_key()

A função PHP array_intersect_key() compara dois ou mais arrays pelas suas chaves e retorna um novo array contendo as entradas do primeiro array cujas chaves existem em todos os outros arrays. É importante destacar que ela ignora completamente os valores — apenas as chaves determinam o que é mantido, e os valores retornados são sempre os do primeiro array. Esta página explica como a função funciona, quando utilizá-la e os problemas mais comuns que podem surgir.

Propósito

array_intersect_key() responde à pergunta: "Quais entradas deste array também aparecem — por chave — em todos esses outros arrays?" Um uso prático comum é a lista de permissões de entradas de formulário ou configurações: você mantém apenas as chaves que você permite explicitamente e descarta todo o resto em uma única chamada.

Ela pertence à mesma família que array_intersect(), que compara por valor, e array_diff_key(), que retorna as chaves ausentes dos outros arrays.

Sintaxe

array_intersect_key(array $array, array ...$arrays): array

Uma entrada é mantida somente se a sua chave estiver presente em todos os arrays fornecidos. Os pares chave/valor originais do primeiro array são preservados no resultado.

Exemplos

Comparando dois arrays

As chaves compartilhadas por ambos os arrays são a e b, então essas entradas são mantidas. Observe que os valores diferem para a chave b (brown vs yellow) — isso não importa, apenas a chave precisa corresponder, e o valor vem de $array1. O elemento "red" sem chave em $array1 recebe a chave numérica implícita 0, que está ausente em $array2, portanto é descartado:

Array
(
    [a] => green
    [b] => brown
)

Comparando três arrays

Ao passar mais de dois arrays, uma chave deve aparecer em todos os arrays para ser mantida.

Apenas a chave a está presente nos três arrays. A chave b está ausente em $array3 e a chave c está ausente em $array2, portanto ambas são descartadas:

Array
(
    [a] => green
)

Filtrando um array por suas chaves com lista de permissões

O uso mais prático de array_intersect_key() é filtrar um array associativo para um conjunto aprovado de chaves — por exemplo, aceitar apenas campos conhecidos de uma entrada do usuário:

<?php

$input = array(
    "name"     => "Ann",
    "email"    => "[email protected]",
    "is_admin" => true,        // attacker-supplied field we must ignore
);

$allowed = array("name" => "", "email" => "");

$safe = array_intersect_key($input, $allowed);
print_r($safe);

?>

Os valores de $allowed são irrelevantes — ele atua puramente como uma lista de chaves permitidas. O campo perigoso is_admin é removido:

Array
(
    [name] => Ann
    [email] => [email protected]
)

Pontos importantes

• Apenas as chaves são comparadas, nunca os valores. Duas entradas com a mesma chave mas valores diferentes ainda correspondem. Os valores retornados vêm sempre do primeiro array.
• A ordem dos arrays não muda quais chaves são mantidas, mas a ordem das entradas no resultado segue o primeiro array.
• A comparação de chaves é sensível a maiúsculas e minúsculas para chaves string: "A" e "a" são chaves diferentes.
• Chaves numéricas são comparadas como inteiros. A chave string "1" e a chave inteira 1 são tratadas como a mesma chave, porque o PHP normaliza chaves de array com string numérica para inteiros.
• Passar um único array simplesmente retorna esse array inalterado; passar um argumento que não é array gera um TypeError.

Funções relacionadas

• array_intersect() — interseção por valor em vez de chave.
• array_intersect_assoc() — corresponde tanto à chave quanto ao valor.
• array_diff_key() — o inverso: mantém entradas cujas chaves não estão nos outros arrays.
• array_key_exists() — verifica uma única chave.
• Trabalhando com arrays PHP — a referência completa de arrays.

Prática