PHP array_diff() Function: Usage and Examples

When working with PHP arrays, you may need to find values that appear in one array but not in another. For example, you might want to identify unfinished tasks, available courses, or items missing from a list.

PHP provides the array_diff() function to compare array values and return those that are missing from other arrays.

In this guide, you'll learn how array_diff() works, how it handles array keys, and how to use it in practical situations.

What Is array_diff() in PHP?

The array_diff() function compares the values of one array against one or more other arrays.

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

Its syntax is:

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

The parameters are:

• $array — The original array containing the values you want to check.
• ...$arrays — Optional additional arrays to compare against. In PHP 8+, at least one array is required overall.

The function returns a new array and leaves the original arrays unchanged.

Example 1: Comparing Two Arrays

Let's compare two lists of colors.

<?php

$colors = ["Red", "Green", "Blue", "Yellow"];

$excluded = ["Green", "Yellow"];

$result = array_diff($colors, $excluded);

print_r($result);

Output:

Array
(
    [0] => Red
    [2] => Blue
)

The result contains Red and Blue because neither appears in the second array.

Notice that the original array keys, 0 and 2, are preserved.

If you want sequential numeric keys, use array_values():

$result = array_values(
    array_diff($colors, $excluded)
);

The result will then have keys 0 and 1.

Example 2: Comparing Multiple Arrays

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

<?php

$languages = [
    "PHP",
    "Python",
    "JavaScript",
    "Go"
];

$frontend = ["JavaScript"];

$excluded = ["Go"];

$result = array_diff(
    $languages,
    $frontend,
    $excluded
);

print_r($result);

Output:

Array
(
    [0] => PHP
    [1] => Python
)

PHP removes values found in either comparison array.

Important: The comparison is directional. array_diff($a, $b) does not necessarily return the same result as array_diff($b, $a).

Example 3: Comparing Associative Arrays

The array_diff() function compares values, not keys.

For example:

<?php

$skills = [
    "backend" => "PHP",
    "database" => "MySQL",
    "frontend" => "JavaScript"
];

$knownSkills = [
    "language1" => "PHP",
    "language2" => "JavaScript"
];

$result = array_diff($skills, $knownSkills);

print_r($result);

Output:

Array
(
    [database] => MySQL
)

Even though the array keys are different, PHP matches the values and removes PHP and JavaScript from the result.

If you need to compare both keys and values, use array_diff_assoc() instead.

Practical Example: Finding Incomplete Courses

Imagine you're building a learning platform that tracks completed courses.

You have one array containing all available courses and another containing courses a student has finished.

Let's identify the courses the student still needs to complete.

Create a file named remaining-courses.php:

<?php

declare(strict_types=1);

$availableCourses = [
    "PHP Basics",
    "PHP Arrays",
    "PHP Functions",
    "PHP OOP",
    "PHP File Handling"
];

$completedCourses = [
    "PHP Basics",
    "PHP Functions"
];

// Find courses that are not completed.

$remainingCourses = array_diff(
    $availableCourses,
    $completedCourses
);

// Display the result.

echo "<h2>Remaining Courses</h2>";

echo "<ul>";

foreach ($remainingCourses as $course) {

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

echo "</ul>";

Browser output:

Remaining Courses

PHP Arrays
PHP OOP
PHP File Handling

The function automatically removes completed courses from the available course list.

This approach also works for comparing user permissions, checking missing items, and filtering previously processed records.

Important Comparison Rules

There are a few behaviors worth remembering:

• Keys are preserved: The returned array retains the original keys from the first array.
• Comparison is case-sensitive: "PHP" and "php" are different values.
• Matching duplicates are removed: If a value appears in a comparison array, every occurrence of that value in the first array is excluded.
• Unmatched duplicates remain: The function doesn't automatically remove duplicate values that aren't excluded.
• Values are compared as strings: For example, integer 10 and string "10" are considered equal.
• Only one level is compared: array_diff() is not designed to compare nested arrays directly.

The string-based comparison is especially important when your arrays contain mixed data types. Use appropriate validation or a custom comparison function when exact type-sensitive matching is required.

array_diff() vs Related Functions

Choose the function based on whether you need to compare values, keys, or both.

Key Takeaways

• array_diff() compares array values and returns those missing from the comparison arrays.
• Only entries from the first array appear in the result.
• You can compare against multiple arrays.
• The function preserves the original array keys.
• Use array_values() to reindex the result when needed.
• Use array_diff_assoc() when keys must also match.
• Be aware of case sensitivity, string-based comparisons, and duplicate values.

The array_diff() function is a convenient way to identify missing or unmatched values in PHP arrays. It helps simplify comparisons without requiring manual loops, making it useful for filtering lists, comparing records, and identifying differences between datasets.

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