array_unshift()

¿Buscas una función potente para agregar nuevos elementos al inicio de un array en PHP? La función array_unshift() es exactamente lo que necesitas. Con ella puedes añadir uno o más elementos al principio de un array, reindexando automáticamente las claves numéricas y desplazando los elementos existentes a posiciones más altas.

¿Qué es array_unshift()?

La función array_unshift() es una función integrada de PHP que añade uno o más elementos al inicio de un array. No reemplaza los elementos existentes, sino que los desplaza a índices más altos para hacer espacio a los nuevos. Piensa en ella como la imagen especular de array_push(), que agrega elementos al final.

Sintaxis

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

• $array — el array al que se va a anteponer. Se pasa por referencia, por lo que la variable original se modifica directamente.
• $values — uno o más valores que se añaden al principio. Se listan de izquierda a derecha y aparecen en ese mismo orden al inicio del array.

La función devuelve el nuevo número de elementos del array (un entero), no el array en sí.

Ejemplo básico

Añadimos "orange" y "lemon" al inicio de $fruits. Las claves numéricas se reindexan automáticamente comenzando desde 0, y el valor de retorno 5 es el nuevo número de elementos. La salida es:

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

Cómo se manejan las claves

Esta es la fuente de sorpresas más habitual. array_unshift() trata de forma diferente las claves numéricas y las de string:

• Las claves numéricas se reinician. Todas las claves enteras existentes se renumeran comenzando desde 0. Las claves enteras personalizadas que hayas definido se pierden.
• Las claves string (asociativas) se conservan. Solo los elementos recién añadidos al principio reciben claves numéricas (0, 1, …); las claves string existentes conservan sus nombres.

<?php

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

?>

Salida — observa que "name" se mantiene, pero 10 y 20 pasan a ser 1 y 2:

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

Cuándo usarla

• Construir una cola o lista donde los nuevos elementos deben estar al frente (los más recientes primero).
• Añadir una fila de encabezado o un valor predeterminado antes de los datos existentes.
• Revertir el efecto de array_shift(), que elimina el primer elemento.

Una nota sobre el rendimiento: como cada elemento existente debe ser reindexado y desplazado, array_unshift() es O(n) — más lenta que array_push(), que es O(1). Para arrays muy grandes dentro de un bucle muy utilizado, es preferible agregar al final y revertir una sola vez al terminar, o usar una estructura como SplDoublyLinkedList.

Funciones relacionadas

• array_push() — añade elementos al final de un array.
• array_shift() — elimina el primer elemento.
• array_splice() — inserta o elimina elementos en cualquier posición.
• array_merge() — combina dos o más arrays.

Práctica