PHP Array Search: Подробное руководство

array_search() находит первый элемент array, равный заданному значению, и возвращает ключ этого элемента. Если совпадений нет, функция возвращает false. Используйте её, когда у вас есть значение и нужно знать, где оно находится в array — например, чтобы получить индекс для передачи в unset(), array_splice() или дальнейшего поиска.

Функция работает как с индексированными, так и с ассоциативными array и возвращает настоящий ключ — им может быть 0, непоследовательное целое число или string. На этой странице рассматриваются синтаксис, нестрогое и строгое сравнение, ловушка с false и 0, поиск всех совпадений (а не только первого), а также случаи, когда лучше воспользоваться in_array() или array_keys().

Синтаксис

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

• $needle — искомое значение.
• $haystack — array, в котором выполняется поиск.
• $strict — необязательный параметр. Если false (значение по умолчанию), значения сравниваются нестрого (==), поэтому 0, "0", 0.0 и даже false могут совпасть друг с другом. Если true, используется строгое сравнение (===): типы и значения должны совпадать одновременно. Всегда передавайте true, если array содержит значения разных типов.

Функция возвращает ключ первого совпадающего элемента или false, если значение не найдено.

Базовое использование

Простейший случай: поиск в индексированном array и вывод ключа, по которому находится значение.

Здесь 3 находится по индексу 2, поэтому скрипт выведет Value was found at key: 2. Обратите внимание: array_search() возвращает реальный ключ, а не позицию — для переиндексированного или ассоциативного array это не одно и то же.

Поиск в ассоциативных array

array_search() особенно полезна для ассоциативных array: она возвращает string-ключ, который можно использовать для получения связанных данных:

<?php

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

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

?>

Результат: Bob's role is: editor. Если вам нужно только проверить наличие значения, а не узнать его ключ, предпочтительнее in_array() — она нагляднее и чуть быстрее.

Строгое и нестрогое сравнение

По умолчанию array_search() сравнивает нестрого (==), что может давать неожиданные совпадения при различии типов. Передача true в качестве третьего аргумента включает строгое (===) сравнение, при котором типы тоже должны совпадать:

В этом примере создан array $array из пяти элементов, включая string-значение "3". Затем задано искомое значение 3. Функция array_search() выполняет поиск в array с параметром strict, установленным в true. Результат сохраняется в переменной $result. Далее оператор if проверяет, найдено ли значение. Если найдено — выводится ключ; если нет — сообщение об отсутствии значения в array. Обратите внимание: array_search() возвращает false, когда значение не найдено. Поскольку 0 является допустимым ключом, необходимо использовать строгое сравнение (=== false), чтобы правильно различить отсутствие результата и ключ 0.

Ловушка с false и 0

Самая распространённая ошибка при работе с array_search() — неверная интерпретация возвращаемого значения. Так как у найденного элемента может быть ключ 0, а «не найдено» возвращает false, нестрогая проверка if (!$result) воспринимает оба случая одинаково. Всегда сравнивайте с помощью === 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
}

?>

Результат: Found at key: 0. Наивная проверка if (!$key) ошибочно сообщила бы «Not found».

Поиск всех совпадающих ключей

array_search() останавливается на первом совпадении. Чтобы получить ключи всех элементов, равных заданному значению, используйте array_keys() с необязательным аргументом поиска:

<?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() возвращает 1, а array_keys($scores, 20) — все индексы, содержащие 20 (1 и 3).

Когда что использовать

Итог

array_search() возвращает ключ первого элемента, равного искомому значению, или false, если такого элемента нет. Запомните главное: передавайте strict = true, если array содержит значения разных типов; всегда проверяйте результат через === false; используйте in_array() или array_keys(), когда нужен ответ «да/нет» или все совпадающие ключи.

Практика