array_diff_uassoc
Compares arrays by key and value, using a user callback to decide when two keys are equal.
array_diff_uassoc(array $array, array ...$arrays, callable $key_compare_func): array- Added in PHP 5.0.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The array to compare from. |
$arraysoptional | array | One or more arrays to compare against (variadic). |
$key_compare_func | callable | Comparison function for the keys, called as callback(mixed $a, mixed $b): int. It must return a value less than, equal to, or greater than zero. |
Return value
arrayAn array of entries from $array that were not matched in any other array, where values are compared internally as strings and keys are compared by the callback.
Errors
Values are cast to string for comparison, so array values raise an "Array to string conversion" warning and objects without __toString() raise an error.
array_diff_uassoc() is array_diff_assoc() with one part swapped out: the values are still compared internally as strings, but the keys are compared by a callback you supply. An entry is kept when no other array contains a key the callback calls equal holding the same value.
When to reach for it
Use it when key equality is looser than exact string identity. Diffing HTTP headers where one side spelled them Content-Type and the other content-type, comparing config arrays where one source prefixes keys with a section name, or matching keys after trimming whitespace all need this. The callback is a three-way comparator like the one usort() takes, so strcasecmp can be passed by name and the spaceship operator covers most custom cases.
What trips people up
The callback goes last, after every array. If you put it second, PHP raises a TypeError about the argument type.
Only the keys use your callback. Values still go through the internal string comparison, so if you need custom value logic reach for array_udiff_assoc(), or array_udiff_uassoc() to customise both.
Non-integer returns from the callback are cast to int, so returning 0.5 is read as 0, meaning "equal".
Example
When to use it
- Diff two header arrays where one side capitalises names and the other does not
- Compare a namespaced config against a flat one by stripping the prefix inside the callback
- Match keys after trimming stray whitespace introduced by a CSV or INI import
Frequently asked questions
Where does the callback go in array_diff_uassoc?
Always last, after every array you are comparing against. Putting it in second position causes a TypeError because that slot expects an array.
What is the difference between array_diff_uassoc and array_udiff_assoc?
array_diff_uassoc uses your callback for the keys and the internal string comparison for the values; array_udiff_assoc does the opposite. Use array_udiff_uassoc() when you need custom logic for both.
What must the callback return?
An integer that is negative, zero, or positive, exactly like a usort() comparator — zero means the two keys are equal. Non-integer returns are cast to int, so 0.5 is read as 0 and treated as a match.
More examples
Ignoring a key prefix
The callback compares only the part after the version prefix, so v2:name pairs with v1:name and is dropped because both hold 'Ada'. Only v2:role survives, because the role value actually changed.
<?php
$current = ['v2:name' => 'Ada', 'v2:role' => 'admin'];
$saved = ['v1:name' => 'Ada', 'v1:role' => 'dev'];
$strip = fn($k) => substr((string) $k, 3);
print_r(array_diff_uassoc($current, $saved, fn($a, $b) => strcmp($strip($a), $strip($b))));Comparing against several arrays
Every array before the callback is subtracted. 'A' matches 'a' and 'B' matches 'b' case-insensitively with equal values, so only C => 3 is left.
<?php
$a = ['A' => 1, 'B' => 2, 'C' => 3];
$b = ['a' => 1];
$c = ['b' => 2];
print_r(array_diff_uassoc($a, $b, $c, 'strcasecmp'));The callback only touches keys
The first call still returns k => YES: the keys matched case-insensitively, but the values 'YES' and 'yes' are compared internally as exact strings and differ. The second call returns an empty array once the value matches exactly too.
<?php
$a = ['k' => 'YES'];
$b = ['K' => 'yes'];
print_r(array_diff_uassoc($a, $b, 'strcasecmp'));
print_r(array_diff_uassoc($a, ['K' => 'YES'], 'strcasecmp'));
Discussion