Understanding PHP Array Intersect Key Function

The array_intersect_ukey() function compares the keys of two or more arrays using a callback you supply, and returns the entries from the first array whose keys are present in every other array. The u in the name stands for user-supplied comparison — it is the key-aware sibling of array_intersect_key(), the difference being that you decide when two keys count as "the same".

This page explains what the function returns, how the comparison callback drives the result, and the gotchas worth knowing before you use it.

When Would I Use It?

Reach for array_intersect_ukey() when you need to keep only the entries whose keys overlap, but plain key equality is not enough. Typical cases:

• Case-insensitive key matching — treat Host and host as the same key.
• Normalized keys — ignore whitespace, prefixes, or formatting differences before comparing.
• Filtering a config or request array down to keys that also appear in a whitelist of allowed keys.

If you only need exact key matching, use the simpler built-in array_intersect_key() instead — no callback required.

Syntax

array_intersect_ukey(
    array $array1,
    array $array2,
    array ...$arrays,
    callable $key_compare_func
): array

Parameters & Return Value

Returns: An array containing every key-value pair from $array1 whose key matches a key in all of the other arrays. A key matches when the callback returns 0.

Note: the values come only from $array1. The values stored under matching keys in the other arrays are ignored — only their keys matter.

Basic Example

<?php

function key_compare_func($key1, $key2)
{
    if ($key1 == $key2)
        return 0;
    else if ($key1 > $key2)
        return 1;
    else
        return -1;
}

$array1 = ['a' => 'green', 'b' => 'brown', 'c' => 'blue', 'red' => 3];
$array2 = ['d' => 'green', 'b' => 'yellow',  'yellow' => 10, 'red' => 'game'];
$result = array_intersect_ukey($array1, $array2, 'key_compare_func');

print_r($result);

?>

Output:

Array
(
    [b] => brown
    [red] => 3
)

The callback compares keys like the spaceship operator does: it returns 0 only when two keys are equal. The keys b and red exist in both arrays, so their entries are kept — with the values from $array1 (brown and 3), not from $array2.

In modern PHP you can replace that whole helper with the spaceship operator (<=>):

<?php

$array1 = ['a' => 'green', 'b' => 'brown', 'c' => 'blue', 'red' => 3];
$array2 = ['d' => 'green', 'b' => 'yellow',  'red' => 'game'];

$result = array_intersect_ukey(
    $array1,
    $array2,
    fn($k1, $k2) => $k1 <=> $k2
);

print_r($result);

?>

Output:

Array
(
    [b] => brown
    [red] => 3
)

Case-Insensitive Key Matching

This is where the callback earns its place. strcasecmp() already returns the integer contract the function expects (0 when equal, ignoring case), so you can pass it directly to match keys regardless of capitalization:

<?php

$config   = ['Host' => 'localhost', 'PORT' => 8080, 'Debug' => true];
$defaults = ['host' => '0.0.0.0', 'port' => 80, 'timeout' => 30];

$shared = array_intersect_ukey($config, $defaults, 'strcasecmp');

print_r($shared);

?>

Output:

Array
(
    [Host] => localhost
    [PORT] => 8080
)

Host matches host and PORT matches port even though their casing differs, so both survive. Debug has no counterpart in $defaults, so it is dropped. Notice the kept keys and values are exactly as written in the first array.

Gotchas

• The callback must return 0 for a match. A common mistake is writing a callback that returns a boolean ($k1 === $k2). true/false cast to 1/0, so non-equal keys would accidentally "match". Always return a three-way comparison integer.
• Values come from the first array only. If two arrays share a key but hold different values, the result keeps the first array's value.
• The callback is the last argument, even when you pass three or more arrays to compare against.
• For comparing both keys and values, see array_intersect_uassoc(); for the opposite operation (keys that are not shared), see array_diff_ukey().

Conclusion

array_intersect_ukey() filters an array down to the entries whose keys also appear in every other array, using your own definition of key equality. Use it for case-insensitive or normalized key matching; fall back to array_intersect_key() when exact matching is all you need. The key rule to remember: the callback must return 0 for equal keys, and the resulting values always come from the first array.

Practice