Entendendo a Função PHP "array_key_exists"

array_key_exists() é uma função PHP integrada que verifica se uma determinada chave existe em um array. Ela retorna true quando a chave está presente e false quando não está — independentemente do valor armazenado nessa chave. Esta página explica como a função funciona, como ela difere de isset() (a fonte mais comum de bugs) e quando você deve usar cada uma.

Sintaxe

array_key_exists(string|int $key, array $array): bool

• $key — a chave a ser pesquisada. As chaves de array em PHP são sempre inteiros ou strings, portanto $key deve ser um desses tipos.
• $array — o array em que pesquisar.
• Valor de retorno — true se $key é uma chave de $array, caso contrário false.

Note que ela verifica a chave, não o valor. Para pesquisar um valor em vez disso, use in_array() ou array_search().

Exemplo básico

array_key_exists() é mais útil com arrays associativos, onde as chaves têm nomes em vez de números.

A saída é:

The key 'first_name' exists in the array.

Ela também funciona com chaves inteiras — incluindo os índices numéricos automáticos de uma lista simples:

<?php

$colors = ['red', 'green', 'blue']; // keys are 0, 1, 2

var_dump(array_key_exists(2, $colors)); // bool(true)
var_dump(array_key_exists(3, $colors)); // bool(false)

Saída:

bool(true)
bool(false)

array_key_exists() vs. isset()

Este é o aspecto mais importante a entender sobre a função. Ambas podem testar uma chave, mas respondem perguntas diferentes:

• array_key_exists($key, $array) retorna true se a chave estiver definida mesmo quando seu valor for null.
• isset($array[$key]) retorna false quando o valor é null, porque isset() verifica se uma variável existe e não é null.

<?php

$data = ['name' => null];

var_dump(array_key_exists('name', $data)); // bool(true)  — the key is there
var_dump(isset($data['name']));            // bool(false) — value is null

Saída:

bool(true)
bool(false)

Use array_key_exists() quando um valor null for significativo (por exemplo, "o campo foi enviado mas deixado em branco"). Use isset() quando você só se importa se há um valor utilizável e não null presente — ele também é ligeiramente mais rápido para o caso comum.

Quando usar

• Proteger contra avisos de "chave de array indefinida" antes de ler uma chave que pode estar ausente.
• Validar que as chaves obrigatórias existem em uma configuração ou entrada de formulário.
• Distinguir uma chave definida como null de uma chave genuinamente ausente.

Armadilhas comuns

• É sensível a maiúsculas e minúsculas para chaves string. 'Name' e 'name' são chaves diferentes.
• Não pesquisa arrays aninhados. Ela verifica apenas o nível superior do array passado.
• Não analisa valores. Pesquisar 'John' como chave em ['first_name' => 'John'] retorna false. Use in_array() para pesquisar por valor.
• Para listar todas as chaves de uma vez, veja array_keys().

Conclusão

array_key_exists() é uma ferramenta pequena, mas essencial para trabalhar com segurança com arrays PHP. Use-a quando precisar saber se uma chave está definida — e lembre-se de que, ao contrário de isset(), ela trata uma chave contendo null como existente.

Prática