array_intersect_key()

Purpose

array_intersect_key() filters one array by comparing its keys with the keys of other arrays. It returns the entries of the first array whose keys are present in every other array you pass. Values in the other arrays are never compared and never returned. Those arrays only act as a set of allowed keys.

The typical use is a whitelist: you have a large associative array, such as submitted form data or a database-shaped record, and you want to keep only a known set of fields.

Signature

Parameters and defaults

• $array: the master array. Its entries, its key order and its values are what end up in the result.
• ...$arrays: zero or more arrays whose keys are checked. An entry from $array survives only if its key exists in each of these arrays.

There are no optional settings. Since PHP 8.0.0 the function can be called with only one argument. In that case no other array can remove anything, so the result contains all the entries of $array.

Return value and failure cases

The function always returns an array. If no key is shared by all the arrays, the result is an empty array. Keys from $array are preserved, including integer keys, and the original order of $array is kept.

Passing something that is not an array, such as null or a string, throws a TypeError. The function does not return false to signal an error.

Two keys count as equal when (string) $key1 === (string) $key2. In practice PHP already normalizes numeric string keys such as '3' to the integer 3 when an array is built, so '3' and 3 refer to the same key. A key such as '03' stays a string and does not match 3.

Example 1: whitelisting fields

Because only keys matter, the second argument can hold any values. array_flip() turns a list of allowed names into an array that uses those names as keys.

<?php
$user = ['id' => 7, 'name' => 'Ada', 'email' => 'ada@example.com', 'password_hash' => 'x9'];
$allowed = array_flip(['id', 'name', 'email']);
echo json_encode(array_intersect_key($user, $allowed), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"id":7,"name":"Ada","email":"ada@example.com"}

The password_hash entry is dropped because $allowed has no such key. The order of the result follows $user, not $allowed.

Example 2: several arrays and differing values

When you pass more than two arrays, a key must appear in all of them. The values come from the first array only, even when the others hold different values for the same key.

<?php
$a = ['blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4];
$b = ['green' => 5, 'blue' => 6, 'yellow' => 7];
$c = ['blue' => 'x', 'green' => 'y', 'red' => 'z'];
echo json_encode(array_intersect_key($a, $b, $c)), "\n";

{"blue":1,"green":3}

red is missing from $b, and purple is missing from both of the others, so only blue and green remain, with the values 1 and 3 from $a.

Example 3: integer keys are preserved

The function does not renumber keys. If you apply it to a list, the result may have gaps. Use array_values() when you need a sequential list again.

<?php
$list = ['a', 'b', 'c', 'd'];
$result = array_intersect_key($list, [0 => true, 2 => true, '3' => true]);
echo json_encode($result), "\n";
echo json_encode(array_values($result)), "\n";

{"0":"a","2":"c","3":"d"}
["a","c","d"]

The first line is an object in JSON because the keys are 0, 2 and 3, which are not a continuous sequence starting at zero. After array_values() the keys are 0, 1 and 2, so the second line is a JSON list.

Edge cases

• Null values count. Only key presence matters. An entry such as 'note' => null is kept if 'note' exists in the other arrays. This differs from isset(), which treats null as missing.
• Empty arrays. If any array you pass is empty, the result is empty, because no key can be present in all arguments.
• Single argument. array_intersect_key($array) returns the same entries as $array.
• Nested arrays. The comparison is shallow. Only top-level keys are examined, and nested values are returned unchanged.
• Duplicates. Array keys are unique, so there is nothing to deduplicate in the result.

Common mistakes

1. Passing a plain list as the second argument. array_intersect_key($user, ['id', 'name']) checks the keys 0 and 1, not the strings id and name. Flip the list first or build it with the names as keys.
2. Expecting values to be compared. If you need the value to match as well, use array_intersect_assoc(). If you want to compare values only, use array_intersect().
3. Expecting values from the later arrays. The result always holds the values of the first array. Swap the argument order if you want the other array's values.
4. Assuming the result is reindexed. Integer keys stay as they were, which can surprise code that loops with a for index.
5. Passing null. A missing or null array triggers a TypeError. Cast or default it, for example with ?? [], before calling.

Related functions

• array_diff_key(): the opposite, keeping entries whose keys are absent from the other arrays.
• array_intersect_assoc(): requires both key and value to match.
• array_intersect_ukey(): compares keys with your own callback.
• array_intersect(): compares values only.
• array_flip(): handy for turning a list of names into a key set.
• array_filter() with ARRAY_FILTER_USE_KEY: filters by a key condition expressed as code.

Recap

array_intersect_key() returns the entries of the first array whose keys exist in all other arrays. It ignores the other arrays' values, keeps the first array's keys and order, returns an empty array when nothing matches, and throws a TypeError for non-array arguments. Use it with array_flip() for tidy field whitelists.