PHP 遞歸轉換陣列鍵名大小寫：recurse_array_change_key_case 實作與應用

需求場景

對接第三方 API、舊系統遷移、資料庫結果集合併時，鍵名大小寫不一致（如 UserID vs user_id），需統一轉換為小寫或大寫，且支援多維陣列遞歸處理。

核心實作

<?php
/**
 * 遞歸轉換陣列所有字串鍵名大小寫
 *
 * @param array  $array  目標陣列（引用傳遞，直接修改）
 * @param int    $case   CASE_LOWER (預設) 或 CASE_UPPER
 * @return void
 */
function recurse_array_change_key_case(array &$array, int $case = CASE_LOWER): void {
    foreach ($array as $key => $value) {
        // 僅處理字串鍵名
        if (!is_string($key)) continue;

        $newKey = $case === CASE_UPPER ? strtoupper($key) : strtolower($key);

        if ($newKey !== $key) {
            unset($array[$key]);
            $array[$newKey] = $value;
            $key = $newKey; // 更新 $key 供後續遞歸使用
        }

        // 遞歸處理子陣列
        if (is_array($value)) {
            recurse_array_change_key_case($array[$key], $case);
        }
    }
}

// 使用範例
$data = [
    'UserID' => 123,
    'UserName' => 'Gonn',
    'Profile' => [
        'Email' => 'gonn@example.com',
        'Address' => [
            'City' => 'Taipei',
            'ZipCode' => '100'
        ]
    ],
    'Tags' => ['PHP', 'Laravel'],
];

recurse_array_change_key_case($data, CASE_LOWER);
print_r($data);
/* 輸出：
Array
(
    [userid] => 123
    [username] => Gonn
    [profile] => Array
        (
            [email] => gonn@example.com
            [address] => Array
                (
                    [city] => Taipei
                    [zipcode] => 100
                )
        )
    [tags] => Array
        (
            [0] => PHP
            [1] => Laravel
        )
)
*/

進階：函數式風格（返回新陣列，不修改原值）

<?php
function array_change_key_case_recursive(array $array, int $case = CASE_LOWER): array {
    $result = [];
    foreach ($array as $key => $value) {
        $newKey = is_string($key)
            ? ($case === CASE_UPPER ? strtoupper($key) : strtolower($key))
            : $key;
        $result[$newKey] = is_array($value)
            ? array_change_key_case_recursive($value, $case)
            : $value;
    }
    return $result;
}

// 使用
$normalized = array_change_key_case_recursive($originalData, CASE_LOWER);

效能與注意事項

• 引用修改版（recurse_array_change_key_case）記憶體效率高，適合大陣列。
• 函數式版本（array_change_key_case_recursive）不可變，適合函數式編程、並發安全。
• 鍵名衝突：轉換後可能出現重複鍵（如 UserID 和 userid 同為 userid），後者會覆蓋前者。建議轉換前檢查或業務保證不衝突。
• 非字串鍵（整數、物件）保持不變。

實戰：統一 API 回應鍵名

<?php
class ApiResponseNormalizer {
    public static function normalize(mixed $data): mixed {
        if (is_array($data)) {
            recurse_array_change_key_case($data, CASE_LOWER);
            // 進一步規範：snake_case 轉 camelCase 等
            return $data;
        }
        if (is_object($data)) {
            // 物件轉陣列處理
            return self::normalize((array) $data);
        }
        return $data;
    }
}

// 中介層自動處理
$response = $httpClient->get('/api/users/1')->json();
$normalized = ApiResponseNormalizer::normalize($response);

總結

recurse_array_change_key_case 以簡潔的遞歸邏輯解決多維陣列鍵名大小寫不一致問題。根據場景選擇引用修改或函數式風格，並注意鍵名衝突風險。納入專案工具庫，可大幅減少對接時的手動轉換代碼。