array_change_key_case()

Функция PHP array_change_key_case()

array_change_key_case() возвращает копию array, в которой все строковые ключи приведены к нижнему или верхнему регистру. Функция наиболее полезна для нормализации ключей, поступающих из непредсказуемого источника — HTTP-заголовков, заголовков столбцов CSV, строк базы данных или пользовательского ввода, — чтобы остальной код мог обращаться к ним по единственному, заранее известному регистру.

На этой странице рассматриваются синтаксис, параметры, возвращаемое значение, подводные камни с числовыми ключами и коллизиями ключей, а также несколько практических рецептов.

Синтаксис

array_change_key_case(array $array, int $case = CASE_LOWER): array

Функция возвращает новый array с ключами в изменённом регистре; исходный array остаётся нетронутым. Затрагиваются только строковые ключи — целочисленные ключи возвращаются без изменений (см. Числовые ключи игнорируются ниже).

Базовый пример: ключи в верхнем регистре

Вывод:

Array
(
    [FIRST_NAME] => John
    [LAST_NAME] => Doe
)

Ключи теперь в верхнем регистре, тогда как значения (John, Doe) остались без изменений.

Поведение по умолчанию: нижний регистр

Если аргумент $case не указан, по умолчанию используется CASE_LOWER, и ключи приводятся к нижнему регистру. Это наиболее распространённый сценарий — нормализация ввода в смешанном регистре перед чтением:

<?php

$headers = array("Content-Type" => "text/html", "X-Powered-By" => "PHP");

// No second argument → CASE_LOWER
$normalized = array_change_key_case($headers);

echo $normalized["content-type"]; // text/html

Вывод:

text/html

Теперь вы всегда можете обращаться к $normalized["content-type"] независимо от того, в каком регистре изначально был записан заголовок.

Числовые ключи игнорируются

array_change_key_case() затрагивает только строковые ключи. Целочисленные ключи передаются без изменений, поэтому индексированный array возвращается точно в том же виде, в каком был передан:

<?php

$mixed = array("Name" => "Ada", 0 => "zero", "Age" => 36);
print_r(array_change_key_case($mixed, CASE_UPPER));

Вывод:

Array
(
    [NAME] => Ada
    [0] => zero
    [AGE] => 36
)

Осторожно: коллизии ключей

Поскольку ключи PHP array должны быть уникальными, приведение регистра может привести к коллизии двух различных ключей. В этом случае побеждает последнее значение, а более раннее запись молча отбрасывается:

<?php

$array = array("Name" => "Ada", "name" => "Grace");
print_r(array_change_key_case($array, CASE_LOWER));

Вывод:

Array
(
    [name] => Grace
)

И "Name", и "name" становятся "name", поэтому выживает только последнее присваивание (Grace). Если важно сохранить все записи, проверьте наличие дубликатов без учёта регистра до вызова этой функции.

Изменяется только верхний уровень

Эта функция не является рекурсивной — ключи вложенных array остаются как есть. Чтобы изменить ключи на более глубоких уровнях структуры, необходимо обойти array самостоятельно:

<?php

function changeKeyCaseRecursive(array $array, int $case = CASE_LOWER): array
{
    $result = array_change_key_case($array, $case);
    foreach ($result as $key => $value) {
        if (is_array($value)) {
            $result[$key] = changeKeyCaseRecursive($value, $case);
        }
    }
    return $result;
}

$data = array("User" => array("First" => "Ada"));
print_r(changeKeyCaseRecursive($data, CASE_UPPER));

Вывод:

Array
(
    [USER] => Array
        (
            [FIRST] => Ada
        )

)

Типичные сценарии использования

• Нормализация HTTP-заголовков или параметров запроса, чтобы поиск не зависел от регистра, применяемого отправителем.
• Приведение заголовков столбцов CSV или электронных таблиц к единому виду перед маппингом строк на модель.
• Обеспечение единообразия ключей конфигурации или базы данных в коде, написанном разными людьми.

Связанные функции

• strtolower() и strtoupper() — изменяют регистр строкового значения (эта функция использует их для ключей).
• array_keys() и array_values() — извлекают ключи или значения array.
• array_flip() — меняет ключи и значения местами.
• array_map() — преобразует значения array с помощью функции обратного вызова.
• См. PHP Arrays для общего обзора.

Практика