Understanding PHP's array_diff_uassoc Function

array_diff_uassoc() compares two (or more) arrays with an additional key check, and lets you supply your own function for comparing the keys. It returns every entry from the first array whose key/value pair is not matched in any of the other arrays. This page explains the signature, walks through exactly how the matching works, and shows when to reach for it instead of the simpler array-diff functions.

The "u" in the name stands for user-supplied key comparison; the "assoc" means the keys are checked too (an associative comparison).

Signature

array_diff_uassoc(
    array $array,
    array ...$arrays,
    callable $key_compare_func
): array

• $array — the array to compare from. Its entries appear in the result.
• $arrays — one or more arrays to compare against.
• $key_compare_func — a callback fn(mixed $a, mixed $b): int that returns 0 when two keys are considered equal, and a negative/positive integer otherwise (the same <=> contract used by usort). Built-ins such as strcasecmp fit this shape.

It returns a new array; the original arrays are not modified.

How the comparison works

This is the part that trips people up. array_diff_uassoc() keeps an entry from $array only if both of these are true for it across the other arrays:

1. The value does not match (values are compared with the regular, loose == after being cast to string — the same rule array_diff() uses), or
2. The key does not match according to your $key_compare_func.

Put the other way around: an entry is dropped only when another array contains the same value under a key your callback treats as equal. So the custom callback governs the keys; the values are still compared by PHP's built-in rule. That last point is the most common misconception — the callback is for keys only.

Example

Compare price lists with case-insensitive keys

Output:

Array
(
    [Banana] => 0.5
    [Cherry] => 3
)

Walking through each entry of $prices:

• Apple => 1.20 — strcasecmp("Apple", "apple") is 0, so the keys match, and the value 1.20 also matches $updated["apple"]. Both match, so it is dropped.
• Banana => 0.50 — the keys match (strcasecmp("Banana", "banana") === 0), but the values differ (0.50 vs 0.75). Because the value does not match, the entry is kept.
• Cherry => 3.00 — no key in $updated matches, so it is kept.

This shows the rule in action: a matching key alone is not enough to remove an entry — the value has to match too.

Related diff functions

array_diff_uassoc() is one of a family of array-difference functions. Pick the one whose comparison strategy matches your data:

• array_diff() — compares values only; keys are ignored.
• array_diff_assoc() — compares keys and values with the built-in rules (no callbacks).
• array_diff_key() — compares keys only, with built-in comparison.
• array_diff_ukey() — compares keys only, but with a callback for the keys.
• array_udiff() — compares values with a callback; keys ignored.
• array_udiff_assoc() — callback for values, built-in check on keys.
• array_udiff_uassoc() — callbacks for both values and keys.

When should you use it?

Reach for array_diff_uassoc() when keys matter to the comparison but the default key-matching is too strict — for example when keys differ only by case or formatting, or when keys are objects/values that need custom logic to be considered "the same." If you only care about values, use array_udiff(); if you need a callback for the values too, use array_udiff_uassoc().

Conclusion

array_diff_uassoc() returns the entries of the first array that have no key/value match in the other arrays, using a callback you provide to decide when two keys are equal. Remember that the values are still compared with PHP's built-in rule — an entry survives unless both its key and its value are matched elsewhere.

Practice