PHP array_diff_key() Function: Usage and Examples

When comparing PHP arrays, sometimes you only need to know which keys exist in one array but are missing from another.

For example, you might want to identify newly added configuration settings, detect missing fields, or compare the structure of two records.

PHP provides the array_diff_key() function for this purpose.

In this guide, you'll learn how it works, how it handles associative and indexed arrays, and how to use it in practical situations.

What Is array_diff_key() in PHP?

The array_diff_key() function compares arrays using their keys only.

It returns entries from the first array whose keys don't appear in any of the comparison arrays.

Its syntax is:

array_diff_key(
    array $array,
    array ...$arrays
): array

The parameters are:

• $array — The original array to compare.
• ...$arrays — Additional arrays whose keys are checked against the first array.

The function returns a new array containing unmatched keys and their original values.

The input arrays remain unchanged. In PHP 8+, calling the function with only one array is also allowed and returns its entries unchanged.

Example 1: Comparing Associative Array Keys

Let's compare two arrays containing user information.

<?php

$user = [
    "name" => "Alex",
    "email" => "[email protected]",
    "role" => "Editor"
];

$requiredFields = [
    "name" => true,
    "email" => true
];

$result = array_diff_key($user, $requiredFields);

print_r($result);

Output:

Array
(
    [role] => Editor
)

The keys name and email exist in both arrays, so they're excluded.

The key role exists only in the first array, so it's included in the result.

Example 2: Array Values Are Ignored

Unlike array_diff() and array_diff_assoc(), this function doesn't compare values.

<?php

$first = [
    "theme" => "light",
    "language" => "en"
];

$second = [
    "theme" => "dark"
];

print_r(array_diff_key($first, $second));

Output:

Array
(
    [language] => en
)

Although the theme values are different, the key exists in both arrays.

Therefore, theme is excluded from the result.

Remember: array_diff_key() detects missing keys, not changed values.

Example 3: Comparing Multiple Arrays

You can compare the first array against several arrays at once.

<?php

$settings = [
    "theme" => "dark",
    "language" => "en",
    "timezone" => "UTC"
];

$groupA = ["theme" => "light"];
$groupB = ["language" => "fr"];

$result = array_diff_key(
    $settings,
    $groupA,
    $groupB
);

print_r($result);

Output:

Array
(
    [timezone] => UTC
)

The function keeps only entries whose keys are absent from every comparison array.

Practical Example: Finding Added and Removed Settings

Imagine you're updating an application's configuration.

You want to identify which configuration keys were added and which were removed between two versions.

Create a file named compare-config.php:

<?php

declare(strict_types=1);

// Previous configuration.

$oldSettings = [
    "site_name" => "My Website",
    "theme" => "light",
    "cache_enabled" => true,
    "legacy_mode" => false
];

// Updated configuration.

$newSettings = [
    "site_name" => "My Website",
    "theme" => "dark",
    "cache_enabled" => false,
    "timezone" => "UTC"
];

// Find newly added keys.

$added = array_diff_key(
    $newSettings,
    $oldSettings
);

// Find removed keys.

$removed = array_diff_key(
    $oldSettings,
    $newSettings
);

// Display the differences.

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

    echo "<p>Added: " . htmlspecialchars(
        (string) $key,
        ENT_QUOTES,
        "UTF-8"
    ) . "</p>";
}

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

    echo "<p>Removed: " . htmlspecialchars(
        (string) $key,
        ENT_QUOTES,
        "UTF-8"
    ) . "</p>";
}

Browser output:

Added: timezone
Removed: legacy_mode

By reversing the argument order, the application can identify both newly added and removed keys.

Notice that changes to theme and cache_enabled are not reported because those keys exist in both configurations.

This approach is useful for configuration migrations, comparing record structures, and checking changes to application settings.

How Does array_diff_key() Handle Numeric Keys?

The function also works with indexed arrays, where the keys are integers.

<?php

$first = [10, 20, 30];

$second = [100, 200];

print_r(array_diff_key($first, $second));

Output:

Array
(
    [2] => 30
)

The first two indexes exist in both arrays. Only index 2 is missing from the second array.

The original keys are preserved in the result.

String keys are case-sensitive, so "Name" and "name" are different keys. PHP also normalizes certain numeric string keys into integers when arrays are created.

array_diff_key() vs Related Functions

Choose array_diff_key() when the existence of a key matters more than its associated value.

Common Mistakes

• Expecting changed values: The function ignores values entirely.
• Expecting a two-way comparison: Reverse the arguments to find keys missing from the other direction.
• Expecting recursive comparison: Only top-level keys are checked.
• Confusing numeric indexes with values: Indexed arrays are compared by position, not by their stored elements.
• Expecting new numeric indexes: The result preserves keys from the first array.

Key Takeaways

• array_diff_key() compares array keys rather than values.
• It returns entries from the first array whose keys are missing from the comparison arrays.
• The function works with associative and indexed arrays.
• You can compare multiple arrays in a single call.
• The original array keys and values are preserved.
• Comparisons are directional and operate on one array level.

The array_diff_key() function is a straightforward way to identify missing keys in PHP arrays. It's especially useful when comparing configuration structures, validating expected fields, and detecting added or removed entries without manually looping through arrays.

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