array_unshift()

Procura uma função eficaz para adicionar novos elementos ao início de um array em PHP? Conheça a função array_unshift(). Com ela, você pode facilmente adicionar um ou mais elementos ao início de um array, reindexando automaticamente as chaves numéricas e deslocando os elementos existentes para posições maiores.

O que é array_unshift()?

A função array_unshift() é uma função nativa do PHP que adiciona um ou mais elementos ao início de um array. Ela não substitui os elementos existentes — ela os desloca para índices maiores para abrir espaço para os novos. Pense nela como a imagem espelhada de array_push(), que acrescenta ao final.

Sintaxe

array_unshift(array &$array, mixed ...$values): int

• $array — o array ao qual os elementos serão adicionados no início. É passado por referência, portanto a variável original é modificada diretamente.
• $values — um ou mais valores a serem adicionados no início. Listados da esquerda para a direita, eles aparecem na mesma ordem no início do array.

A função retorna o novo número de elementos no array (um inteiro), não o array em si.

Exemplo básico

Adicionamos "orange" e "lemon" ao início de $fruits. As chaves numéricas são reindexadas automaticamente a partir de 0, e o valor de retorno 5 é o novo total de elementos. A saída é:

5
Array
(
    [0] => orange
    [1] => lemon
    [2] => apple
    [3] => banana
    [4] => cherry
)

Como as chaves são tratadas

Esta é a fonte mais comum de surpresas. array_unshift() trata chaves numéricas e string de forma diferente:

• Chaves numéricas são reiniciadas. Todas as chaves inteiras existentes são renumeradas a partir de 0. Quaisquer chaves inteiras personalizadas que você definiu são perdidas.
• Chaves string (associativas) são preservadas. Apenas os elementos recém-adicionados recebem chaves numéricas (0, 1, …); as chaves string existentes mantêm seus nomes.

<?php

$data = array("name" => "Alice", 10 => "ten", 20 => "twenty");
array_unshift($data, "first");
print_r($data);

?>

Saída — observe que "name" permanece, mas 10 e 20 passam a ser 1 e 2:

Array
(
    [0] => first
    [name] => Alice
    [1] => ten
    [2] => twenty
)

Quando usar

• Construção de uma fila ou lista em que os novos itens pertencem ao início (os mais recentes primeiro).
• Adição de uma linha de cabeçalho ou valor padrão antes dos dados existentes.
• Reverter o efeito de array_shift(), que remove o primeiro elemento.

Uma observação sobre desempenho: como cada elemento existente precisa ser reindexado e deslocado, array_unshift() é O(n) — mais lento que array_push(), que é O(1). Para arrays muito grandes dentro de um loop intenso, prefira empilhar e inverter uma única vez ao final, ou use uma estrutura como SplDoublyLinkedList.

Funções relacionadas

• array_push() — adiciona elementos ao final de um array.
• array_shift() — remove o primeiro elemento.
• array_splice() — insere ou remove elementos em qualquer posição.
• array_merge() — combina dois ou mais arrays.

Prática