PHP array_diff_ukey() 函式詳解：自訂鍵名比較的純鍵名差集運算

array_diff_ukey() 專注於「鍵名」單一維度比較，並支援自訂回調函式定義鍵名相等邏輯。適用於鍵名為複雜型別（物件、日期字串、浮點數）或需特定排序規則（自然排序、版本號比較）的差集運算場景。

函式簽名與參數

array_diff_ukey(array $array, array ...$arrays, callable $keyCompareFunc): array

核心行為：純鍵名集合差

• 完全忽略值：值不參與任何比較，即使值不同，鍵名經回調判定相同即視為「存在」。
• 保留鍵值關聯：結果保留基準陣列原始鍵名與對應值。
• 回調契約：必須實現三向比較（<0, 0, >0），違反傳遞性會導致未定義行為。

實戰範例解析

範例 1：基本數值鍵名差集

<?php
$a1 = [0 => 'Dog', 1 => 'Cat', 2 => 'Horse'];
$a2 = [3 => 'Rat', 1 => 'Bird', 5 => 'Monkey'];

$result = array_diff_ukey($a1, $a2, 'keyCompareStandard');
print_r($result);
// 輸出：
// Array (
//     [0] => Dog
//     [2] => Horse
// )
// 解析：鍵 1 存在於 $a2 → 排除；鍵 0、2 僅在 $a1 → 保留
?>

範例 2：三陣列比較

<?php
$a1 = [0 => 'Dog', 1 => 'Cat', 2 => 'Horse'];
$a2 = [3 => 'Rat', 1 => 'Bird', 5 => 'Monkey'];
$a3 = [6 => 'Dog', 7 => 'Donkey', 0 => 'Horse'];

$result = array_diff_ukey($a1, $a2, $a3, 'keyCompareStandard');
print_r($result);
// 輸出：
// Array (
//     [2] => Horse
// )
// 解析：
// 鍵 0：$a3 有鍵 0 → 排除
// 鍵 1：$a2 有鍵 1 → 排除
// 鍵 2：$a2、$a3 均無鍵 2 → 保留
?>

範例 3：版本號字串鍵名自然排序比較

<?php
$installed = [
    '1.0.0' => 'core',
    '1.2.3' => 'module-a',
    '2.0.0-beta' => 'module-b',
    '2.0.0' => 'module-c'
];
$available = [
    '1.0.0' => 'core',
    '1.2.3' => 'module-a',
    '2.0.0' => 'module-c',
    '2.1.0' => 'module-d'
];

// 版本號感知比較（需 PHP 8.0+ strnatcmp 或 version_compare 封裝）
function versionKeyCompare(string $a, string $b): int {
    return version_compare($a, $b);
}

$missing = array_diff_ukey($available, $installed, 'versionKeyCompare');
print_r($missing);
// 輸出：
// Array (
//     [2.1.0] => module-d
// )
// 應用：發現可用但未安裝的版本
?>

範例 4：DateTime 物件鍵名比較

<?php
$schedule1 = [
    new DateTime('2024-01-01 09:00') => 'Meeting A',
    new DateTime('2024-01-01 14:00') => 'Meeting B',
];
$schedule2 = [
    new DateTime('2024-01-01 09:00') => 'Meeting A (updated)',
    new DateTime('2024-01-02 09:00') => 'Meeting C',
];

function dateTimeKeyCompare(DateTime $a, DateTime $b): int {
    return $a <=> $b; // PHP 7.0+ 太空船運算子
}

$unique = array_diff_ukey($schedule1, $schedule2, 'dateTimeKeyCompare');
print_r($unique);
// 輸出：僅保留 2024-01-01 14:00 的 Meeting B
?>

函式族群快速選型表

效能與注意事項

• 回調函式在 PHP 層執行，大陣列（>10萬鍵）效能明顯低於內建函式，建議預先將複雜鍵名正規化為可用內建比較的標量。
• 嚴格遵守回調契約：cmp(a,b) === -cmp(b,a) 且傳遞性成立，否則排序/比較行為未定義。
• PHP 8.0+ 可直接使用 fn($a,$b) => $a <=> $b 簡化標準三向比較回調。

array_diff_ukey() 讓鍵名差集運算突破型別限制，是處理版本管理、時序資料、物件索引等進階場景的關鍵工具。