O Guia Completo da Função array_pad do PHP

Arrays são fundamentais em praticamente todo programa PHP e, às vezes, você precisa que um array tenha um comprimento garantido — preenchido com valores reservados quando ficar abaixo do tamanho desejado. A função array_pad do PHP faz exatamente isso: ela retorna uma cópia do array crescida até um tamanho alvo, com um valor de sua escolha preenchendo as novas posições. Este guia aborda sua sintaxe, como o sinal do tamanho controla a direção do preenchimento, os comportamentos que costumam pegar as pessoas de surpresa e exemplos executáveis.

O Que a Função array_pad Faz

array_pad retorna um novo array preenchido até um comprimento que você especifica. Duas regras governam seu comportamento:

• Se o tamanho solicitado for maior que o array de entrada, cópias do valor de preenchimento são adicionadas — no final quando o tamanho é positivo, no início quando é negativo.
• Se o tamanho solicitado for menor ou igual ao comprimento atual do array, o array é retornado sem alterações. array_pad nunca remove elementos.

O array original não é modificado; você trabalha com o valor retornado.

Sintaxe da Função array_pad

array_pad(array $array, int $length, mixed $value): array

• $array: O array de entrada que você deseja preencher. Ele não é modificado.
• $length: O tamanho alvo. Um valor positivo preenche à direita (final); um valor negativo preenche à esquerda (início). O número de elementos adicionados é abs($length) - count($array).
• $value: O valor usado para cada elemento preenchido. Pode ser de qualquer tipo, inclusive outro array.

Casos de Uso da Função array_pad

A função array_pad é útil quando você deseja:

• Garantir que um array tenha pelo menos N elementos antes de iterar sobre posições fixas.
• Alinhar dados à direita ou à esquerda preenchendo o lado oposto.
• Preencher uma grade, formulário ou linha de tabela de tamanho fixo com valores padrão.

Exemplos da Função array_pad

Veja alguns exemplos de como a função array_pad pode ser usada em cenários do mundo real:

Exemplo 1: Preenchimento no Final (Tamanho Positivo)

Saída:

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

O array de entrada $numbers tem 3 elementos e o tamanho alvo é 5, portanto 5 - 3 = 2 zeros são adicionados ao final.

Exemplo 2: Preenchimento no Início (Tamanho Negativo)

Saída:

Array
(
    [0] => black
    [1] => black
    [2] => red
    [3] => green
    [4] => blue
)

O tamanho -5 é negativo, portanto o preenchimento vai para o início. As 3 cores originais mantêm sua ordem e abs(-5) - 3 = 2 cópias de 'black' são adicionadas ao começo. Note que as chaves são reindexadas a partir de 0 independentemente da direção.

Exemplo 3: Preenchendo um Array com um Valor Específico

Saída:

Array
(
    [0] => a
    [1] => b
    [2] => c
    [3] => z
    [4] => z
    [5] => z
    [6] => z
)

O array de entrada tem 3 elementos e o tamanho alvo é 7, portanto 7 - 3 = 4 cópias de 'z' são adicionadas.

Comportamentos Inesperados e Casos Extremos

Alguns comportamentos costumam pegar as pessoas de surpresa:

• Ele nunca reduz um array. Se abs($length) for menor ou igual à contagem atual, o array é retornado sem alterações. Para remover elementos, use array_slice ou array_splice.
• Chaves string são mantidas, mas o preenchimento é sempre numérico. Ao preencher um array associativo, as chaves string existentes são preservadas e os novos elementos recebem chaves inteiras sequenciais:

<?php

$scores = array('math' => 90, 'science' => 85);
print_r(array_pad($scores, 4, 0));

?>

Array
(
    [math] => 90
    [science] => 85
    [0] => 0
    [1] => 0
)

• O valor de preenchimento pode ser de qualquer tipo. Passar um array como $value insere cópias desse array inteiro, o que é útil para construir grades de linhas padrão.
• O preenchimento é fixo, não interpolado. Cada nova posição recebe exatamente o mesmo $value. Se você precisar de um preenchimento gerado ou sequencial, construa-o com array_fill ou range().

Funções Relacionadas

• array_fill — cria um novo array preenchido inteiramente com um valor.
• array_merge — combina arrays em vez de preencher um.
• array_slice e array_splice — extraem ou removem partes de um array.
• array_chunk — divide um array preenchido em grupos de tamanho fixo.

Conclusão

array_pad é a maneira mais rápida de garantir que um array tenha um determinado comprimento sem escrever um loop. Lembre-se das duas regras que guiam seu comportamento: um tamanho positivo preenche o final, um tamanho negativo preenche o início, e um tamanho igual ou inferior ao comprimento atual deixa o array intocado. Com isso em mente — mais o comportamento de chaves e os casos extremos acima — você pode recorrer ao array_pad sempre que precisar de arrays de tamanho fixo e previsível em seus projetos PHP.

Prática