range()

Introdução

range() é uma função nativa do PHP que constrói um array contendo uma sequência de elementos de um valor inicial até um valor final. Em vez de escrever um loop para inserir números ou letras em um array um por um, você descreve os extremos (e opcionalmente um passo) e o PHP preenche tudo o que há no meio.

Esta página abrange a sintaxe, todos os tipos de intervalo que podem ser gerados (crescente, decrescente, inteiros, floats e caracteres), as armadilhas que pegam as pessoas de surpresa e onde range() se encaixa em código real.

Sintaxe

range(string|int|float $start, string|int|float $end, int|float $step = 1): array

Onde:

• $start: O primeiro valor da sequência.
• $end: O último valor da sequência.
• $step: Opcional. A quantidade adicionada entre os valores. O padrão é 1. Deve ser um número positivo — range() determina a direção a partir de $start e $end, não pelo sinal do passo.

Dois pontos valem a pena memorizar desde já:

• Ambos os extremos são incluídos. range(0, 5) retorna seis elementos (0 a 5), não cinco.
• O resultado é sempre um novo array com índice zero — as chaves são 0, 1, 2, … independentemente dos valores internos.

Exemplos

Gerar números de 0 a 5

A chamada mais simples recebe um início e um fim. Observe que 5 está incluído no resultado:

Saída:

Array
(
    [0] => 0
    [1] => 1
    [2] => 2
    [3] => 3
    [4] => 4
    [5] => 5
)

Usar números negativos

$start e $end podem ser negativos, e a sequência ainda avança de 1 em 1:

Saída:

Array
(
    [0] => -5
    [1] => -4
    [2] => -3
    [3] => -2
    [4] => -1
    [5] => 0
    [6] => 1
    [7] => 2
    [8] => 3
    [9] => 4
    [10] => 5
)

Pular valores

O terceiro argumento define o incremento. Aqui é 2, portanto apenas números pares são produzidos:

Saída:

Array
(
    [0] => 0
    [1] => 2
    [2] => 4
    [3] => 6
    [4] => 8
    [5] => 10
)

Gerar um intervalo de caracteres

Quando $start e $end são caracteres únicos, range() percorre o alfabeto entre eles. Isso é útil para construir menus de A a Z, rótulos de colunas ou fixtures de teste:

Saída:

Array
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
    [6] => g
    [7] => h
    [8] => i
    [9] => j
    [10] => k
    [11] => l
    [12] => m
    [13] => n
    [14] => o
    [15] => p
    [16] => q
    [17] => r
    [18] => s
    [19] => t
    [20] => u
    [21] => v
    [22] => w
    [23] => x
    [24] => y
    [25] => z
)

Contar regressivamente com um intervalo decrescente

Se $start for maior que $end, range() conta de forma decrescente automaticamente. Você não passa um passo negativo — o passo permanece positivo:

<?php

$countdown = range(5, 1);
print_r($countdown);

Saída:

Array
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Usar um passo float

O passo pode ser um float, o que permite construir sequências fracionárias — útil para sliders, eixos de gráficos ou valores amostrados:

<?php

$fractions = range(0, 1, 0.25);
print_r($fractions);

Saída:

Array
(
    [0] => 0
    [1] => 0.25
    [2] => 0.5
    [3] => 0.75
    [4] => 1
)

Armadilhas comuns

• O intervalo é inclusivo. range(1, 3) retorna [1, 2, 3]. Se você esperava um resultado com comprimento igual a $end, ficará errado por um.
• Mantenha o passo positivo. A direção vem da ordem de $start e $end. Passar um passo negativo (por exemplo range(0, 5, -1)) é um erro — versões mais antigas do PHP emitiam um aviso, enquanto o PHP 8.3+ lança um ValueError. Um passo igual a 0 também é inválido.
• O último elemento pode ser ignorado. range(0, 10, 3) produz [0, 3, 6, 9] — 10 não é alcançável a partir de 0 em passos de 3, então a sequência para no último valor que cabe.
• Floats podem ser imprecisos. Como os números de ponto flutuante não conseguem representar todos os decimais com exatidão, um passo como 0.1 pode não resultar no valor esperado. Arredonde os resultados, ou avance sobre inteiros e divida depois, quando a precisão for importante.
• A memória cresce com o tamanho. range(0, 1000000) constrói um array de um milhão de elementos na memória. Se você só precisa iterar, um loop for ou SplFixedArray evita a alocação.

Quando usar range()

range() brilha sempre que você precisa de uma sequência pronta em vez de um container vazio:

• Conduzir um loop. Combine com foreach para iterar sobre um intervalo fixo: foreach (range(1, 12) as $month) { … }.
• Construir listas de opções — anos, dias do mês ou letras de A a Z para um dropdown.
• Combinar com array_map() para transformar cada valor, por exemplo array_map(fn($n) => $n * $n, range(1, 5)) para obter quadrados.

Se em vez disso você quiser um array com o mesmo valor repetido, use array_fill() em vez de range(). Para saber mais sobre arrays em geral, consulte o guia de arrays PHP.

Resumo

range() cria um array com índice zero de valores sequenciais entre dois extremos. Funciona com inteiros, floats e caracteres, conta para cima ou para baixo e aceita um passo opcional. Lembre-se de que ambos os extremos são inclusivos, o passo é sempre positivo e intervalos grandes alocam memória real — e se torna um dos one-liners mais convenientes do PHP.

Prática