array_change_key_case()

Função PHP array_change_key_case()

array_change_key_case() retorna uma cópia de um array com todas as suas chaves string convertidas para minúsculas ou maiúsculas. É mais útil para normalizar chaves que vêm de uma fonte imprevisível — cabeçalhos HTTP, títulos de colunas CSV, linhas de banco de dados ou entrada do usuário — para que o restante do código possa consultá-las com uma capitalização única e conhecida.

Esta página cobre a sintaxe, os parâmetros, o valor de retorno, as armadilhas relacionadas a chaves numéricas e colisões de chaves, além de algumas receitas práticas.

Sintaxe

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

A função retorna um novo array com as chaves convertidas; o array original permanece intacto. Apenas chaves string são afetadas — chaves inteiras são retornadas sem alteração (veja Chaves numéricas são ignoradas abaixo).

Exemplo básico: converter chaves para maiúsculas

Saída:

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

As chaves agora estão em maiúsculas, enquanto os valores (John, Doe) permanecem intactos.

Comportamento padrão: minúsculas

Quando você omite o argumento $case, o padrão é CASE_LOWER, portanto as chaves se tornam minúsculas. Este é o uso mais comum — normalizar entradas com capitalização mista antes de lê-las:

<?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

Saída:

text/html

Agora você pode sempre ler $normalized["content-type"] independentemente de como o cabeçalho foi originalmente capitalizado.

Chaves numéricas são ignoradas

array_change_key_case() afeta apenas chaves string. Chaves inteiras passam sem alteração, portanto um array indexado é retornado exatamente como foi passado:

<?php

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

Saída:

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

Atenção às colisões de chaves

Como as chaves de um array PHP devem ser únicas, a conversão de capitalização pode fazer com que duas chaves distintas colidam. Quando isso acontece, o último valor prevalece e a entrada anterior é silenciosamente descartada:

<?php

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

Saída:

Array
(
    [name] => Grace
)

Tanto "Name" quanto "name" se tornam "name", portanto apenas a última atribuição (Grace) sobrevive. Se preservar todas as entradas for importante, verifique duplicatas sem distinção de maiúsculas/minúsculas antes de chamar esta função.

Apenas o nível superior é alterado

Esta função não é recursiva — as chaves de arrays aninhados são mantidas como estão. Para alterar chaves em níveis mais profundos da estrutura, você deve percorrer o array manualmente:

<?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));

Saída:

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

)

Casos de uso comuns

• Normalizar cabeçalhos HTTP ou parâmetros de consulta para que as buscas não dependam da capitalização do remetente.
• Limpar cabeçalhos de colunas de CSV ou planilhas antes de mapear linhas para o seu modelo.
• Tornar consistentes chaves de configuração ou banco de dados em código escrito por pessoas diferentes.

Funções relacionadas

• strtolower() e strtoupper() — alteram a capitalização de um valor string (esta função as utiliza nas chaves).
• array_keys() e array_values() — extraem as chaves ou valores de um array.
• array_flip() — troca chaves e valores.
• array_map() — transforma valores de um array com um callback.
• Veja PHP Arrays para uma visão geral mais ampla.

Prática