PHP array_is_list() Function: Usage and Examples

PHP arrays can store both ordered lists and key-value collections. Sometimes, your application needs to know whether an array has sequential numeric keys or uses a different structure.

The array_is_list() function checks whether an array qualifies as a list, making it useful for validating data structures and working with indexed arrays.

What Is array_is_list() in PHP?

The array_is_list() function determines whether an array contains consecutive integer keys starting from zero, in the correct order.

Its syntax is:

array_is_list(array $array): bool

The function accepts one array and returns:

• true if its keys are 0, 1, 2, 3... in that order.
• false if it contains missing, reordered, or non-sequential keys.

PHP version requirement: array_is_list() was introduced in PHP 8.1.

Example 1: Checking an Indexed Array

Let's check whether a simple list of programming languages qualifies as a PHP list.

<?php

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

var_dump(array_is_list($languages));

Output:

bool(true)

The array contains three elements with consecutive keys 0, 1, and 2.

The actual values don't matter. A valid list can contain strings, numbers, objects, or other data types.

Example 2: Checking Associative and Non-Sequential Arrays

Associative arrays with named keys don't qualify as lists.

<?php

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

var_dump(array_is_list($user));

Output:

bool(false)

The same applies to arrays with gaps or numeric keys in the wrong order.

<?php

// Missing index 1.
$first = [
    0 => "PHP",
    2 => "Python"
];

// Keys are out of order.
$second = [
    1 => "PHP",
    0 => "Python"
];

var_dump(array_is_list($first));
var_dump(array_is_list($second));

Output:

bool(false)
bool(false)

Even though the second array contains keys 0 and 1, they appear in the wrong order.

A valid list must have the correct sequence of keys, not simply contain numeric indexes.

What Happens with Empty Arrays?

An empty array is considered a valid list.

<?php

$items = [];

var_dump(array_is_list($items));

Output:

bool(true)

This is expected because an empty array has no keys that violate the required sequence.

If your application requires a non-empty list, combine both checks:

$valid = $items !== [] && array_is_list($items);

Converting an Array into a List

Some operations preserve original array keys, which can leave gaps in numeric indexes.

For example, array_filter() keeps the keys of matching elements.

<?php

$numbers = [5, 10, 15, 20];

$filtered = array_filter(
    $numbers,
    fn(int $number): bool => $number > 10
);

var_dump(array_is_list($filtered));

// Rebuild consecutive numeric keys.
$filtered = array_values($filtered);

var_dump(array_is_list($filtered));

Output:

bool(false)
bool(true)

The array_values() function creates a new array with sequential numeric keys, starting at zero.

Important: Reindexing removes existing key associations. Don't use array_values() when keys contain meaningful identifiers that must be preserved.

Practical Example: Validating a Product List

Imagine an application receives product records from an API. The application expects a list of products rather than an associative array indexed by product IDs.

You can use array_is_list() to check the outer array's structure before processing it.

Create a file named validate-products.php:

<?php

declare(strict_types=1);

$products = [
    [
        "name" => "Keyboard",
        "stock" => 12
    ],
    [
        "name" => "Mouse",
        "stock" => 5
    ]
];

// Validate the collection structure.
if (!array_is_list($products) || $products === []) {
    exit("Expected a non-empty product list.");
}

// Validate individual records.
foreach ($products as $product) {

    if (
        !is_array($product) ||
        !isset($product["name"], $product["stock"]) ||
        !is_string($product["name"]) ||
        !is_int($product["stock"]) ||
        $product["stock"] < 0
    ) {
        exit("Invalid product record.");
    }
}

// Display the products.
echo "<ul>";

foreach ($products as $product) {

    $message = $product["name"]
        . " - "
        . $product["stock"]
        . " in stock";

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

echo "</ul>";

Browser output:

Keyboard - 12 in stock
Mouse - 5 in stock

If the outer array uses product IDs as keys, such as 101 and 102, array_is_list() returns false.

Notice that the function checks only the structure of the supplied array. It doesn't validate the product records inside it, which is why the example includes separate field validation.

array_is_list() vs Related Functions

Use array_is_list() when you only need to determine whether an existing array has list-style keys.

Key Takeaways

• array_is_list() was introduced in PHP 8.1.
• A valid list has consecutive integer keys starting at zero, in order.
• Associative arrays and arrays with missing or reordered keys return false.
• Empty arrays return true.
• The function examines array keys, not element values.
• Use array_values() to reindex an array when appropriate.

The array_is_list() function provides a simple way to check array structure in PHP. It's particularly useful when validating collections, processing API data, and distinguishing sequential lists from key-value arrays.

For more information, see the official PHP array_is_list() documentation.