PHP array_intersect_ukey() Function: Usage and Examples

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

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

The array_intersect_ukey() function lets you find matching array keys using your own comparison rules.

What Is array_intersect_ukey() in PHP?

The array_intersect_ukey() function compares array keys using a custom callback and returns the matching entries from the first array.

Its syntax is:

array_intersect_ukey(
    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 defining how keys are compared.

An entry is included only when its key has a match in every comparison array.

Important: The function compares keys only. Values are ignored, and the result preserves the original keys and values from the first array.

Example 1: Case-Insensitive Key Comparison

PHP normally treats "Name" and "name" as different keys.

Using strcasecmp(), you can compare string keys without distinguishing uppercase and lowercase ASCII letters.

<?php

$first = [
    "Name" => "Alex",
    "Email" => "[email protected]",
    "Role" => "Editor"
];

$second = [
    "name" => "Taylor",
    "email" => "[email protected]"
];

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

print_r($result);

Output:

Array
(
    [Name] => Alex
    [Email] => [email protected]
)

The Name and Email keys match those in the second array, even though their capitalization differs.

The values are different, but that doesn't matter. The Role entry is excluded because no matching key exists.

How Does the Comparison Callback Work?

The callback receives two 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 create custom rules when keys use different naming conventions.

For example, this callback treats hyphens and underscores as equivalent:

<?php

$first = [
    "user-name" => "Alex",
    "account-status" => "Active"
];

$second = [
    "user_name" => "Taylor"
];

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

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

    return strcmp(
        $normalize($a),
        $normalize($b)
    );
};

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

print_r($result);

Output:

Array
(
    [user-name] => Alex
)

The callback considers user-name and user_name equivalent.

Comparison callbacks must return proper comparison integers, not booleans, and follow consistent ordering rules.

Practical Example: Selecting Supported Data Fields

Imagine your application receives product information from an external system.

The incoming fields may use different capitalization or separators. You want to keep only fields recognized by your application.

Create a file named supported-fields.php:

<?php

declare(strict_types=1);

// Imported product information.

$incoming = [
    "PRODUCT-ID" => "P-101",
    "PRODUCT-NAME" => "Keyboard",
    "UNIT-PRICE" => 49.99,
    "INTERNAL-NOTE" => "Supplier data"
];

// Supported field names.

$supported = [
    "product_id" => true,
    "product_name" => true,
    "unit_price" => true
];

// Custom key comparison.

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

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

// Keep entries with supported keys.

$filtered = array_intersect_ukey(
    $incoming,
    $supported,
    $compareKeys
);

// Display the result.

echo "<h2>Supported Fields</h2>";

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

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

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

Browser output:

Supported Fields

PRODUCT-ID: P-101
PRODUCT-NAME: Keyboard
UNIT-PRICE: 49.99

The function recognizes the first three fields and excludes INTERNAL-NOTE.

Notice that the returned keys retain their original formatting. The comparison callback does not rename them.

When processing real external input, also validate field values and detect keys that become duplicates after normalization.

Comparing Multiple Arrays

You can compare keys across more than two arrays.

<?php

$first = ["Name" => "Alex", "Role" => "Editor"];
$second = ["name" => "Taylor", "role" => "Admin"];
$third = ["NAME" => "Jordan"];

$result = array_intersect_ukey(
    $first,
    $second,
    $third,
    "strcasecmp"
);

print_r($result);

Output:

Array
(
    [Name] => Alex
)

Only the Name key matches across all three arrays under the callback's rules.

array_intersect_ukey() vs Related Functions

Key Takeaways

• array_intersect_ukey() finds matching array keys using custom comparison rules.
• The callback must return a negative integer, zero, or a positive integer.
• Array values are ignored during comparison.
• A key must match in every comparison array to be included.
• The result preserves the original keys and values from the first array.
• The function is useful when integrating data sources with inconsistent field naming conventions.

Use array_intersect_ukey() when standard key matching isn't flexible enough. It helps identify equivalent fields across associative arrays while keeping comparison rules explicit and reusable.

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