PHP array_intersect_uassoc() Function: Usage and Examples

When comparing associative arrays in PHP, you may need to find matching entries even when their keys use different capitalization or formatting.

For example, one system might use "UserName" while another uses "username".

The array_intersect_uassoc() function lets you find matching key-value pairs while controlling how array keys are compared.

What Is array_intersect_uassoc() in PHP?

The array_intersect_uassoc() function returns entries from the first array whose keys and values match entries in every comparison array.

Unlike array_intersect_assoc(), it allows you to define custom rules for comparing keys.

Its syntax is:

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

The parameters are:

• $array — The first array containing the entries to examine.
• ...$arrays — One or more arrays to compare against.
• $key_compare_func — A callback that determines how array keys are compared.

Important: The callback compares keys only. PHP compares the corresponding values using its built-in string-based comparison rules.

Example 1: Case-Insensitive Key Comparison

Let's compare two configuration arrays that use different capitalization for their keys.

<?php

$first = [
    "Theme" => "dark",
    "Language" => "en",
    "Timezone" => "UTC"
];

$second = [
    "theme" => "dark",
    "language" => "fr",
    "timezone" => "UTC"
];

$result = array_intersect_uassoc(
    $first,
    $second,
    "strcasecmp"
);

print_r($result);

Output:

Array
(
    [Theme] => dark
    [Timezone] => UTC
)

The strcasecmp() function compares strings without distinguishing uppercase and lowercase ASCII letters.

The Theme and Timezone entries match in both their keys and values. The Language entry is excluded because its value differs.

Notice that the result preserves the original keys and values from the first array.

How Does the Comparison Callback Work?

The key comparison callback receives two keys and must return an integer:

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

You can use a built-in comparison function or write your own callback.

For example, to treat hyphens and underscores as equivalent:

<?php

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

$second = [
    "user_name" => "Alex",
    "user_role" => "Admin"
];

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

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

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

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

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

print_r($result);

Output:

Array
(
    [user-name] => Alex
)

The callback considers user-name and user_name equivalent. Their values also match, so the entry is included.

The role entries have equivalent keys but different values, so they're excluded.

Comparison callbacks must produce a consistent ordering. Don't return booleans instead of comparison integers.

Practical Example: Comparing Imported User Records

Imagine your application stores user information locally and also receives records from an external service.

The systems use different naming conventions for field names. You want to identify which fields have matching values in both records.

Create a file named compare-users.php:

<?php

declare(strict_types=1);

// Local user record.

$localUser = [
    "user-name" => "Alex",
    "email-address" => "[email protected]",
    "account-status" => "active"
];

// Record from an external service.

$externalUser = [
    "USER_NAME" => "Alex",
    "EMAIL_ADDRESS" => "[email protected]",
    "ACCOUNT_STATUS" => "active"
];

// Normalize keys for comparison.

$normalizeKey = static fn($key): string =>
    strtolower(
        str_replace("-", "_", (string) $key)
    );

// Compare keys using normalized names.

$compareKeys = static fn($a, $b): int =>
    strcmp(
        $normalizeKey($a),
        $normalizeKey($b)
    );

// Find matching key-value pairs.

$matching = array_intersect_uassoc(
    $localUser,
    $externalUser,
    $compareKeys
);

// Display matching fields.

echo "<h2>Matching User Fields</h2>";

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

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

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

Browser output:

Matching User Fields

user-name: Alex
account-status: active

The function recognizes the user name and account status as matching entries, despite differences in their key formatting.

The email address is excluded because its value differs.

This approach is useful for comparing imported records, synchronizing information, and integrating systems with different field naming conventions.

Important Comparison Rules

Keep these behaviors in mind:

• Custom keys, standard values: The callback controls key comparison, but not value comparison.
• Values are compared as strings: Integer 10 and string "10" are considered equal.
• All arrays must match: When comparing multiple arrays, an entry must have a matching key-value pair in every array.
• Original keys are preserved: The function doesn't rename keys in the returned array.
• No recursive comparison: Nested arrays are not compared automatically.
• Empty results: An empty array means no matching entries were found.

If you need strict type-sensitive value comparisons, use a different comparison strategy or a function that supports a custom value callback.

array_intersect_uassoc() vs Related Functions

Choose array_intersect_uassoc() when both keys and values must match, but the keys require custom comparison rules.

Key Takeaways

• array_intersect_uassoc() finds matching key-value pairs across arrays.
• A custom callback determines whether keys are considered equal.
• The callback must return a negative integer, zero, or a positive integer.
• Values use PHP's built-in string-based comparison.
• The result preserves the original keys and values from the first array.
• The function is useful when comparing records with inconsistent key formatting.

The array_intersect_uassoc() function provides greater flexibility when comparing associative arrays. It is particularly helpful when working with external systems that use different capitalization or naming conventions for equivalent data fields.

For additional details, see the official PHP array_intersect_uassoc() documentation.