PHP Array Search: Um Guia Completo

array_search() encontra o primeiro elemento em um array igual a um valor fornecido e retorna a chave desse elemento. Se nada corresponder, retorna false. Use-o quando você tem um valor e precisa saber onde ele está no array — por exemplo, o índice que você passaria para unset(), array_splice() ou uma consulta subsequente.

Funciona tanto em arrays indexados quanto em arrays associativos, e retorna a chave real — que pode ser 0, um inteiro não sequencial ou uma string. Esta página aborda a sintaxe, comparação solta vs. estrita, a armadilha de false vs. 0, como encontrar todas as ocorrências (não apenas a primeira) e quando usar in_array() ou array_keys() em vez disso.

Sintaxe

array_search(mixed $needle, array $haystack, bool $strict = false): int|string|false

• $needle — o valor que você está procurando.
• $haystack — o array em que a busca será feita.
• $strict — opcional. Quando false (o padrão), os valores são comparados de forma solta (==), portanto 0, "0", 0.0 e até false podem se corresponder. Quando true, a comparação é estrita (===), correspondendo apenas quando tipo e valor são idênticos. Sempre passe true quando o array contiver tipos mistos.

A função retorna a chave do primeiro elemento correspondente, ou false se o valor não estiver presente.

Uso básico

O caso mais simples: pesquise em um array indexado e imprima a chave onde o valor se encontra.

Aqui 3 está no índice 2, então o script imprime Value was found at key: 2. Note que array_search() retorna a chave real, não a posição — para um array reindexado ou associativo, esses não são a mesma coisa.

Pesquisando arrays associativos

array_search() é mais útil em arrays associativos, onde retorna uma chave string que você pode usar para buscar dados relacionados:

<?php

$users = [
    "admin"  => "Alice",
    "editor" => "Bob",
    "viewer" => "Cara",
];

$role = array_search("Bob", $users);
echo "Bob's role is: $role"; // editor

?>

Isso imprime Bob's role is: editor. Se você só precisa saber se um valor existe — não sua chave — prefira in_array(), que é mais claro e ligeiramente mais rápido.

Comparação estrita vs. solta

Por padrão, array_search() compara de forma solta (==), o que pode produzir correspondências surpreendentes quando os tipos diferem. Definir o terceiro argumento como true força a comparação estrita (===) para que o tipo também precise corresponder:

Neste exemplo, criamos um array chamado $array com cinco elementos, incluindo o valor string "3". Em seguida, definimos o valor que queremos buscar no array como 3. A função array_search() é usada para pesquisar o valor no array, com o parâmetro strict definido como true. O resultado é armazenado na variável $result. Por fim, usamos uma instrução if para verificar se o valor foi encontrado no array ou não. Se o valor for encontrado, a chave é exibida. Se o valor não for encontrado, uma mensagem indicando que o valor não está no array é mostrada. Note que array_search() retorna false quando o valor não é encontrado. Como 0 é uma chave válida, você deve usar comparação estrita (=== false) para distinguir corretamente entre um resultado não encontrado e uma chave de valor 0.

A armadilha de false vs. 0

O erro mais comum com array_search() é interpretar mal seu valor de retorno. Como um elemento encontrado pode legitimamente ter a chave 0, e "não encontrado" retorna false, uma verificação solta como if (!$result) trata os dois da mesma forma. Sempre compare com === false:

<?php

$names = ["Alice", "Bob", "Cara"];

// Alice is at key 0 — a real result, but falsy!
$key = array_search("Alice", $names);

if ($key === false) {
    echo "Not found";
} else {
    echo "Found at key: $key"; // Found at key: 0
}

?>

Isso imprime Found at key: 0. Um simples if (!$key) teria erroneamente reportado "Not found".

Encontrando todas as chaves correspondentes

array_search() para na primeira correspondência. Para obter as chaves de todos os elementos iguais a um valor, use array_keys() com seu argumento de pesquisa opcional:

<?php

$scores = [10, 20, 30, 20, 50];

echo array_search(20, $scores);            // 1  (first match only)
echo "\n";
print_r(array_keys($scores, 20));          // Array ( [0] => 1 [1] => 3 )

?>

array_search() retorna 1, enquanto array_keys($scores, 20) retorna todos os índices que contêm 20 (1 e 3).

Quando usar cada função

Resumo

array_search() retorna a chave do primeiro elemento igual ao seu valor, ou false se não houver nenhum. Lembre-se dos pontos essenciais: passe strict = true quando o array mistura tipos, sempre teste o resultado com === false e use in_array() ou array_keys() quando precisar de uma resposta sim/não ou de todas as chaves correspondentes.

Prática