O Guia Completo da Função array_keys do PHP

array_keys() retorna as chaves (os índices) de um array como um novo array re-indexado numericamente. É uma das formas mais comuns de inspecionar a estrutura de um array: você a utiliza sempre que se importa com quais posições um array possui, em vez dos valores armazenados nelas.

Este capítulo explica a sintaxe, o modo opcional de pesquisa por valor, a diferença entre comparação livre e estrita, e os padrões do dia a dia em que array_keys() é a ferramenta certa.

O que array_keys() faz

Todo array PHP é um mapa ordenado de pares chave → valor. A chave pode ser um inteiro (como em um array indexado simples) ou uma string (como em um array associativo). array_keys() descarta os valores e retorna apenas as chaves, na ordem original, renumeradas a partir de 0:

• Passe um array e você obterá todas as chaves.
• Passe um valor de pesquisa e você obterá apenas as chaves cujo valor corresponde a esse valor de pesquisa.

O resultado é sempre um novo array, portanto o original nunca é modificado. Se, ao contrário, você quiser os valores, use array_values(); se precisar apenas saber se uma chave específica está presente, array_key_exists() é mais eficiente.

Sintaxe

array_keys(array $array, mixed $search_value = ?, bool $strict = false): array

A função sempre retorna um array; sem correspondências, retorna um array vazio, nunca false.

Obtendo todas as chaves de um array

O uso mais comum é extrair todas as chaves de um array associativo:

Saída:

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

O array $keys retornado contém as três chaves string "a", "b" e "c", re-indexadas a partir de 0. Os valores (apple, banana, cherry) foram descartados — apenas as chaves permanecem.

Encontrando as chaves de um valor

Passe um segundo argumento e array_keys() torna-se uma pesquisa: retorna a chave de cada elemento igual a esse valor. Esta é a principal diferença em relação a array_search(), que para na primeira correspondência.

Saída:

Array
(
    [0] => 0
    [1] => 3
)

"apple" aparece nas posições 0 e 3, portanto ambas as chaves são retornadas. Se o valor não for encontrado, você obtém um array vazio.

Comparação livre vs. estrita

Por padrão, a pesquisa por valor usa comparação livre (==), portanto 1, "1" e 1.0 são todos tratados como iguais. Defina o terceiro argumento como true para exigir uma correspondência exata de tipo e valor (===):

<?php

$values = array("1", 1, "one", 1, "1");

// Loose: matches both strings and integers
print_r(array_keys($values, 1));

// Strict: matches only the integer 1
print_r(array_keys($values, 1, true));

?>

Saída:

Array
(
    [0] => 0
    [1] => 1
    [2] => 3
    [3] => 4
)
Array
(
    [0] => 1
    [1] => 3
)

A pesquisa livre corresponde a "1", 1, 1 e "1" (chaves 0, 1, 3, 4), enquanto a pesquisa estrita corresponde apenas aos dois inteiros 1 (chaves 1 e 3). Use $strict = true sempre que seu array misturar strings e números e a distinção for importante.

Chaves de um array multidimensional

array_keys() analisa apenas o nível superior — retorna as chaves do array externo e nunca desce para arrays aninhados. Com um array multidimensional você obtém de volta as chaves externas:

<?php

$matrix = array(
    "row1" => array("a" => 1, "b" => 2),
    "row2" => array("c" => 3),
);
print_r(array_keys($matrix));

?>

Saída:

Array
(
    [0] => row1
    [1] => row2
)

Para coletar as chaves internas também, percorra o resultado e chame array_keys() em cada sub-array.

Iterando sobre chaves

Um padrão frequente é percorrer uma estrutura pelas suas chaves. Como array_keys() fornece uma lista limpa, você pode usar um loop foreach diretamente:

<?php

$prices = array("pen" => 1.20, "book" => 5.00, "bag" => 12.50);

foreach (array_keys($prices) as $item) {
    echo $item . PHP_EOL;
}

?>

Saída:

pen
book
bag

No dia a dia, você frequentemente usaria foreach ($prices as $item => $price) — mas array_keys() é útil quando você precisa da lista de chaves como um valor (para passá-la em outro lugar, contá-la ou comparar as chaves de dois arrays).

Casos de uso comuns e armadilhas

• Contar chaves: count(array_keys($arr)) é o mesmo que count($arr) — prefira count($arr) diretamente.
• Verificar se uma chave existe: não faça in_array($k, array_keys($arr)) — use array_key_exists() ou isset(), que são mais rápidos e claros. (Para verificar um valor, use in_array().)
• O resultado é sempre re-indexado: as próprias chaves do array retornado são 0, 1, 2, … independentemente das chaves originais.
• Sem correspondências retorna []: a forma de pesquisa por valor nunca retorna false, portanto teste com empty() ou count(), não com === false.

Conclusão

array_keys() extrai as chaves de um array, opcionalmente filtradas por valor com comparação livre ou estrita. Use-a para listar chaves, encontrar todas as posições de um valor ou alimentar uma lista de chaves em um loop. Para os valores correspondentes, use array_values(); para testar uma única chave, use array_key_exists(); e para encontrar a primeira correspondência de um valor, use array_search().

Prática