Como funciona a função array_is_list no PHP 8.1?

O PHP 8.1 está atualmente em desenvolvimento ativo e está programado para ser lançado no final do ano de 2021. Neste artigo, vamos falar um pouco sobre a nova função array_is_list.

Como funciona array_is_list?

A função array_is_list retorna um boolean ao verificar se determinado array contém chaves inteiras sequenciais começando do número 0. Em outras palavras, esta função retorna true se o array testado for uma lista de valores. Ou seja, um array cuja todas as chaves são int , que comecem do número 0 e sem "pulos" entre eles.

Veja alguns exemplos que seriam avaliados como verdadeiro:

array_is_list([]); // true
array_is_list([1, 2, 3]); // true
array_is_list(['uva', 2, 3]); // true
array_is_list(['banana', 'maçã']); // true
array_is_list([0 => 'morango', 'pêra']); // true
array_is_list([0 => 'limão', 1 => 'maracujá']); // true

Qualquer array com chaves, não começando de zero ou que não possua todas as chaves como inteiros em ordem sequencial, serão avaliados como false.

Veja:

array_is_list([1 => 'maçã', 'uva']); // false
array_is_list([0 => 'zero', 2 => 'dois']); // false
array_is_list([0 => 'zero', 'nome' => 'Maxters']); // false
array_is_list([1 => 'limão', 0 => 'pêra']); // false

Se você tentar passar qualquer tipo de argumento para essa função, que não seja um array, será lançado um TypeError. Mesmo os tipos iterable não são aceitos como argumento dessa função.

Qual é a importância dessa função?

Há alguns casos onde você pode precisar que o array seja sequencial, como no caso da função json_encode. Por exemplo, se você aplicar json_encode em um array que seria avaliado como false por array_is_list, ao invés de retornar um objeto JSON correspondente a um Array em Javascript, você teria um Object.

Exemplo:

array_is_list([1, 2, 3]); // true
json_encode([1, 2, 3]); // "[1, 2, 3]"
array_is_list([1 => 1, 2, 3]); // false
json_encode([1 => 1, 2, 3]); //  "{"1":1,"2":2,"3":3}"

Polyfill

Para versões anteriores ao PHP 8.1, podemos utilizar um polyfill para suprir a falta da mesma.

Veja:

if (! function_exists('array_is_list')) {
function array_is_list(array $array): bool 
{
    $expected = 0;
    foreach ($array as $i =&gt; $_) {
        if ($i !== $expected) return false;
        $expected++;
    }
    return true;
}

}