array_change_key_case()

Función array_change_key_case() de PHP

array_change_key_case() devuelve una copia de un array con todas sus claves string convertidas a minúsculas o mayúsculas. Es especialmente útil para normalizar claves que provienen de una fuente impredecible — encabezados HTTP, títulos de columnas CSV, filas de base de datos o entrada del usuario — de modo que el resto del código pueda consultarlas con una capitalización conocida y uniforme.

Esta página cubre la sintaxis, los parámetros, el valor de retorno, los problemas relacionados con las claves numéricas y las colisiones de claves, además de algunos ejemplos prácticos.

Sintaxis

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

La función devuelve un nuevo array con las claves convertidas; el array original no se modifica. Solo se ven afectadas las claves string — las claves enteras se devuelven sin cambios (consulta Las claves numéricas se ignoran más abajo).

Ejemplo básico: convertir claves a mayúsculas

Salida:

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

Las claves ahora están en mayúsculas mientras que los valores (John, Doe) permanecen intactos.

Comportamiento predeterminado: convertir a minúsculas

Cuando se omite el argumento $case, el valor predeterminado es CASE_LOWER, por lo que las claves se convierten a minúsculas. Este es el uso más común — normalizar entradas con capitalización mixta antes de leerlas:

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

Salida:

text/html

Ahora siempre puedes leer $normalized["content-type"] independientemente de cómo estuviera escrito originalmente el encabezado.

Las claves numéricas se ignoran

array_change_key_case() solo actúa sobre las claves string. Las claves enteras pasan sin cambios, por lo que un array indexado se devuelve exactamente como se introdujo:

<?php

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

Salida:

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

Cuidado con las colisiones de claves

Dado que las claves de un array PHP deben ser únicas, al cambiar la capitalización pueden colisionar dos claves distintas. Cuando esto ocurre, el último valor prevalece y la entrada anterior se descarta silenciosamente:

<?php

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

Salida:

Array
(
    [name] => Grace
)

Tanto "Name" como "name" se convierten en "name", por lo que solo sobrevive la última asignación (Grace). Si es importante conservar todas las entradas, verifica si existen duplicados insensibles a mayúsculas antes de llamar a esta función.

Solo se modifica el nivel superior

Esta función no es recursiva — las claves de arrays anidados se dejan tal cual. Para cambiar las claves en niveles más profundos de la estructura, debes recorrer el 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));

Salida:

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

)

Casos de uso comunes

• Normalizar encabezados HTTP o parámetros de consulta para que las búsquedas no dependan de la capitalización del remitente.
• Limpiar encabezados de columnas de CSV o hojas de cálculo antes de mapear filas a tu modelo.
• Hacer coherentes las claves de configuración o de base de datos en código escrito por diferentes personas.

Funciones relacionadas

• strtolower() y strtoupper() — cambian el caso de un valor string (esta función las usa en las claves).
• array_keys() y array_values() — extraen las claves o los valores de un array.
• array_flip() — intercambia claves y valores.
• array_map() — transforma los valores de un array con un callback.
• Consulta PHP Arrays para una visión más amplia.

Práctica