Definition and Usage

PHP Version
4.3+

The array_diff_assoc() function compares array differences based on key–value pairs and returns an associative array containing the elements from the first array that are not present in the other arrays.

This function is used to find elements that do not exist in the other arrays by checking whether both the key and the value match at the same time in associative arrays. In other words, an element is considered a match only when both its key and value are identical.

By leveraging this behavior, you can also use the function to identify elements that should be excluded from an associative array based on specific key–value combinations.

It is commonly used for the following purposes:

  • Excluding elements whose key–value pairs are identical to those in another array
  • Checking the differences between associative arrays
  • Removing elements from an associative array based on specific key–value pairs

Basic Example

PHP 
/* Excluding elements whose key–value pairs are identical to those in another array */
$array1 = ['a' => 1, 'b' => 2, 'c' => 3]; // The array being compared
$array2 = ['b' => 2, 'c' => 3, 'd' => 4];

$result = array_diff_assoc($array1, $array2);
print_r($result); // Array ( [a] => 1 )

/* Checking the differences between associative arrays */
$current_user_info = ['id' => 1, 'name' => 'John', 'age' => 30];
$updated_user_info = ['id' => 1, 'name' => 'John', 'age' => 31];

$differences = array_diff_assoc($updated_user_info, $current_user_info);

if (!empty($differences)) {
    echo 'There is modified data. Updated information: ';

    foreach ($differences as $key => $value) {
        echo "$key: $value ";
    }
} else {
    echo 'There is no modified data.';
}
// Output: 'There is modified data. Updated information: age: 31'

/* Removing elements from an associative array based on specific key–value pairs */
$original_array = ['id' => 1, 'name' => 'John', 'age' => 30];

$value_to_remove = 'John';

$result = array_diff_assoc($original_array, ['name' => $value_to_remove]);
print_r($result); // Array ( [id] => 1 [age] => 30 )

While the array_diff_assoc() function is used to find elements that do not exist in other arrays by checking whether both the key and the value match at the same time, the array_diff() function is used to find values that are not present in other arrays by comparing values only, regardless of the keys.

Differences Between the array_diff_assoc() and array_diff() Functions
FunctionDifference
array_diff_assoc() Compares both the keys and the values of arrays.
array_diff() Compares values only, without considering array keys.

Syntax

PHP 
array_diff_assoc(array $array_1, $array_2, $array_3, ...): array

Parameters

Description of the array_diff_assoc() Function Parameters
$array_1 Required. The array used as the base for comparison.
$array_2 Required (optional as of PHP 8.0.0). An array to compare against the first array.
See Changes as of PHP 8.0.0.
$array_3, ... Optional. Additional arrays to compare against the first array. Multiple arrays can be provided.

Return Values

The function compares differences by checking whether key–value pairs match at the same time across two or more arrays, and returns a new associative array composed of the key–value pairs that exist only in the first array and are not present in the other arrays.

If there are no elements that exist only in the first array when compared based on key–value pairs, the function returns an empty array.

PHP 
$array1 = ['a' => 1, 'b' => 2, 'c' => 3];
$array2 = ['a' => 1, 'b' => 2, 'c' => 3];

$result = array_diff_assoc($array1, $array2);
print_r($result); // Array ( )

As of PHP 8.0.0, the array_diff_assoc() function can be called with only a single parameter. Previously, at least two parameters were required.

  • Before PHP 8.0.0, at least two arrays always had to be passed as parameters.
  • As of PHP 8.0.0, it is possible to pass only a single array.

When only a single array is provided, there is no array to compare against, so the given array is returned as is.

PHP As of PHP 8.0.0, it is possible to pass only a single array. 
$array = ['a' => 1, 'b' => 2, 'c' => 3];

$result = array_diff_assoc($array);
print_r($result);

/* Output:
Array
(
    [a] => 1
    [b] => 2
    [c] => 3
)
*/

Things to Keep in Mind

The array_diff_assoc() function compares array differences based on key–value pairs.

When Data Types Differ but String Representations Are the Same

Keys are compared based on identity according to PHP array rules, while values are compared using loose comparison, which does not distinguish between differences in data types.

PHP 
$array1 = ['a' => 1, 'b' => 2, 'c' => '3'];  // '3' is stored as a string
$array2 = ['a' => 1, 'b' => 2, 'c' => 3];    // 3 is stored as an integer

$differences = array_diff_assoc($array1, $array2);

print_r($differences) // Array ( )

In the code above, $array1 and $array2 both contain the values '3' and 3. However, under loose comparison, these two values are considered equal. As a result, the array_diff_assoc() function does not detect this difference and returns an empty array.

String Representations Must Match

Even if the data types are different, values are treated as identical when their string representations are the same. However, the array_diff_assoc() function compares values by first converting each element to a string (string) and then performing a string-based comparison. In other words, even when the data types differ, the values are considered a match only if their forms are identical after being converted to strings.

PHP 
$array1 = array(0, 1, 2);           // Integers 0, 1, 2
$array2 = array('00', '01', '2');   // Strings '00', '01', '2'

$result = array_diff_assoc($array1, $array2);

print_r($result);
/* Output:
Array
(
    [0] => 0
    [1] => 1
)
*/

The integer 2 matches the string '2' and is therefore excluded. However, 0 and 1 are converted to '0' and '1', which do not match '00' and '01'. As a result, they are identified as differences.

Practical Examples

The array_diff_assoc() function can be applied in a variety of real-world scenarios. Below are several practical examples that demonstrate how this function is commonly used.

Permission Checks

PHP 
$current_permissions = ['read' => true, 'write' => true, 'execute' => false];
$required_permissions = ['read' => true, 'write' => true, 'execute' => true];

$missing_permissions = array_diff_assoc($required_permissions, $current_permissions);

if (!empty($missing_permissions)) {
    echo 'The user is missing the following permissions: ' . implode(', ', array_keys($missing_permissions));
} else {
    echo 'All required permissions are granted.';
}

// Output: 'The user is missing the following permissions: execute'

Additional Explanation
The implode() function joins array elements into a string using a custom delimiter.

Additional Explanation
The array_keys() function extracts only the keys from a given array and returns them as a new array.

In this example, the required permissions are compared against the user's current permissions. If a key–value pair does not match exactly, the corresponding permission is considered missing.

Excluding Selected Options

PHP 
$all_options = ['apple' => 1, 'banana' => 2, 'cherry' => 3, 'date' => 4];
$selected_options = ['banana' => 2, 'date' => 4];

$remaining_options = array_diff_assoc($all_options, $selected_options);

echo 'Unselected options: ' . implode(', ', array_keys($remaining_options));
// Output: 'Unselected options: apple, cherry'

This example identifies which options were not selected by comparing the full list of options with the user’s selections.

Finding Changed Files in a Version Control System

PHP 
$committed_files = [
    'file1.txt' => 'hash1',
    'file2.txt' => 'hash2',
    'file3.txt' => 'hash3'
];

$modified_files = [
    'file1.txt' => 'hash1',
    'file3.txt' => 'hash3',
    'file4.txt' => 'hash4'
];

$new_files = array_diff_assoc($modified_files, $committed_files);

if (!empty($new_files)) {
    echo 'Modified or newly added files: ' . implode(', ', array_keys($new_files));
} else {
    echo 'No files have been changed.';
}

// Output: 'Modified or newly added files: file4.txt'

By comparing the list of committed files with the current file state, this example identifies files that are newly added or whose contents differ based on their key–value pairs.

These examples illustrate how array_diff_assoc() can be used to compare associative arrays across different contexts and extract meaningful differences based on exact key–value matches. When used appropriately, this function provides a concise and reliable way to handle associative array comparisons in real-world applications.

References

See also