array_diff
Returns the values of the first array that are not present in any of the other arrays.
array_diff(array $array, array ...$arrays): array- Added in PHP 4.0.1
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The array to compare from. |
$arraysoptional | array | One or more arrays to compare against (variadic). |
Return value
arrayAn array of all entries from $array whose values do not appear in any of the other arrays. The original keys are preserved.
Errors
Values are cast to string for comparison, so an object without a __toString() method raises an error.
Changelog
- PHP 8.0.0Can now be called with a single argument; previously at least two arrays were required.
array_diff() answers "what is in the first array that is not in the others?" It compares values only — keys play no part in the matching — and returns the surviving entries with their original keys intact.
When to reach for it
Use it any time you need a set subtraction: which requested packages are not installed, which uploaded IDs do not exist in the database, which permissions a role is missing, which files on disk are absent from the manifest. Passing several arrays subtracts all of them at once, which is cleaner than chaining calls.
What trips people up
Comparison is done on the string representation: two elements match when (string) $a === (string) $b. That means 0, "0" and 0.0 are all the same value here, while null, false and "" all stringify to "" and are also treated as equal. When you need real type-aware comparison, use array_udiff() with your own callback.
Keys are preserved, so the result of diffing a list is usually not a list any more. That is invisible until json_encode() turns it into an object instead of an array.
Example
When to use it
- Work out which required PHP extensions are missing from the installed list
- Find IDs submitted by a client that do not exist in the database
- Compare a directory listing against a manifest to spot untracked files
Frequently asked questions
Does array_diff compare keys?
No, it compares values only and ignores keys completely when matching. Use array_diff_key() to compare by key, or array_diff_assoc() to require both key and value to match.
Why does array_diff say two different values are equal?
Elements are compared as strings, so anything with the same string representation counts as equal — for example 0 and '0', or null and false and ''. Use array_udiff() with a strict callback when types matter.
Why are the keys in my result not 0, 1, 2?
array_diff preserves the keys from the first array, so removed elements leave gaps in the numbering. Pass the result through array_values() to renumber it as a list.
More examples
Comparison happens on strings
Removing the empty string also removes null and false, because all three cast to "". The integer 0 and the string '0' both survive as "0" — proof that array_diff never looks at types, only at string output.
<?php
$values = [0, '0', null, false, '', 'zero'];
var_dump(array_diff($values, ['']));Subtracting several arrays at once
Both comparison arrays are subtracted in one call, leaving 'delete' and 'billing'. array_values() renumbers the gaps so the result is a clean list ready for JSON.
<?php
$all = ['read', 'write', 'delete', 'admin', 'billing'];
$granted = ['read', 'write'];
$reserved = ['admin'];
print_r(array_values(array_diff($all, $granted, $reserved)));Diffing in both directions
array_diff is not symmetric, so a full change report needs two calls. The first shows what disappeared (a.txt), the second what is new (d.txt).
<?php
$before = ['a.txt', 'b.txt', 'c.txt'];
$after = ['b.txt', 'c.txt', 'd.txt'];
echo "removed: ", implode(',', array_diff($before, $after)), "\n";
echo "added: ", implode(',', array_diff($after, $before)), "\n";
Discussion