PHP array_diff_uassoc() Function: Usage and Examples

When comparing associative arrays in PHP, you may need more control over how their keys are compared. For example, two systems might use "Email" and "email" for the same field.

The array_diff_uassoc() function lets you compare array values while using a custom callback to determine whether their keys match.

In this guide, you'll learn how the function works, how to write key comparison callbacks, and how to identify differences between records.

What Is array_diff_uassoc() in PHP?

The array_diff_uassoc() function compares entries from one array against other arrays, checking both their keys and values.

Unlike array_diff_assoc(), it uses a callback function to compare the keys.

Its syntax is:

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

The parameters are:

• $array — The original array whose entries are being compared.
• ...$arrays — One or more arrays to compare against.
• $key_compare_func — A callback that determines whether two keys are considered equal.

The function returns entries from the first array that have no matching key-and-value combination in the comparison arrays. It preserves their original keys and does not modify the input arrays.

Example 1: Comparing Keys Without Case Sensitivity

PHP normally treats "Email" and "email" as different array keys.

However, you can use strcasecmp() as the callback to compare string keys without distinguishing uppercase and lowercase ASCII letters.

<?php

$original = [
    "Email" => "[email protected]",
    "Role" => "Editor"
];

$updated = [
    "email" => "[email protected]",
    "role" => "Admin"
];

$result = array_diff_uassoc(
    $updated,
    $original,
    "strcasecmp"
);

print_r($result);

Output:

Array
(
    [role] => Admin
)

The email entries are considered equal because their keys match under the case-insensitive comparison and their values are identical.

The role entries have matching keys but different values, so the updated role appears in the result.

How Does the Comparison Callback Work?

The callback receives two array keys and must return an integer:

• A negative integer if the first key is considered smaller.
• 0 if the keys are considered equal.
• A positive integer if the first key is considered greater.

You can write your own callback when the default key comparison rules aren't suitable.

For example, the following callback treats hyphens and underscores as equivalent:

<?php

$first = [
    "user-name" => "Alex",
    "role" => "Editor"
];

$second = [
    "user_name" => "Alex",
    "role" => "Viewer"
];

$compareKeys = static function ($a, $b): int {

    $left = strtolower(
        str_replace("-", "_", (string) $a)
    );

    $right = strtolower(
        str_replace("-", "_", (string) $b)
    );

    return strcmp($left, $right);
};

$result = array_diff_uassoc(
    $first,
    $second,
    $compareKeys
);

print_r($result);

Output:

Array
(
    [role] => Editor
)

The keys user-name and user_name are considered equivalent by the callback, and their values match.

The role values differ, so that entry remains in the result.

Important: Return a proper comparison integer, not a boolean such as true or false. Comparison callbacks must provide a consistent ordering of keys.

Practical Example: Detecting Configuration Changes

Imagine an application receives updated configuration settings from an external system. The incoming keys sometimes use different capitalization.

We can use array_diff_uassoc() to identify updated or newly added settings while ignoring capitalization differences in the keys.

Create a file named compare-settings.php:

<?php

declare(strict_types=1);

$currentSettings = [
    "Theme" => "light",
    "Language" => "en",
    "PerPage" => 20
];

$newSettings = [
    "theme" => "dark",
    "language" => "en",
    "perpage" => 20,
    "Timezone" => "UTC"
];

// Compare keys without case sensitivity.

$differences = array_diff_uassoc(
    $newSettings,
    $currentSettings,
    static fn($a, $b): int =>
        strcasecmp((string) $a, (string) $b)
);

// Display changed or added settings.

echo "<h2>Configuration Differences</h2>";

foreach ($differences as $key => $value) {

    $message = $key . ": " . $value;

    echo "<p>" . htmlspecialchars(
        $message,
        ENT_QUOTES,
        "UTF-8"
    ) . "</p>";
}

Browser output:

Configuration Differences

theme: dark
Timezone: UTC

The result contains two entries:

• theme — Its value changed from light to dark.
• Timezone — This key did not exist in the original configuration.

The language and perpage entries are excluded because their keys and values match under the comparison rules.

Important Comparison Rules

Before using array_diff_uassoc(), remember these behaviors:

• Only keys use the custom callback. Values are compared using their string representations. For example, integer 10 and string "10" are considered equal.
• Comparison is directional. The function returns unmatched entries from the first array, not both arrays.
• Original keys are preserved. The callback changes how keys are compared, not how they're stored in the result.
• Nested arrays aren't compared recursively. The function operates on one array level.
• Empty results are valid. An empty result means no unmatched entries were found.

When you need to detect entries removed from an updated array, run the comparison again with the arguments reversed.

array_diff_uassoc() vs Related Functions

Choose array_diff_uassoc() when both keys and values matter, but the keys require custom comparison rules.

Key Takeaways

• array_diff_uassoc() compares both array keys and values.
• A user-defined callback controls how keys are compared.
• The callback must return a negative integer, zero, or a positive integer.
• Values use PHP's built-in string-based comparison.
• The function returns unmatched entries from the first array and preserves their keys.
• It is useful for comparing associative records that use different key naming conventions.

The array_diff_uassoc() function gives you additional flexibility when comparing associative arrays. It's particularly useful when working with external data sources, configuration records, and systems that don't use consistent key formatting.

For more information, see the official PHP array_diff_uassoc() documentation.