array_unshift()

Vous cherchez une fonction puissante pour ajouter de nouveaux éléments au début d'un array en PHP ? Ne cherchez pas plus loin que la fonction array_unshift(). Avec cette fonction, vous pouvez facilement ajouter un ou plusieurs éléments au début d'un array, en réindexant automatiquement les clés numériques et en décalant les éléments existants vers des positions supérieures.

Qu'est-ce que array_unshift() ?

La fonction array_unshift() est une fonction PHP intégrée qui ajoute un ou plusieurs éléments au début d'un array. Elle ne remplace pas les éléments existants — elle les décale vers des positions d'index supérieures pour faire de la place aux nouveaux. Considérez-la comme le miroir de array_push(), qui ajoute des éléments à la fin.

Syntaxe

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

• $array — l'array auquel on ajoute des éléments en tête. Il est passé par référence, donc la variable d'origine est modifiée directement.
• $values — une ou plusieurs valeurs à ajouter au début. Listées de gauche à droite, elles apparaissent dans le même ordre au début de l'array.

La fonction retourne le nouveau nombre d'éléments dans l'array (un entier), et non l'array lui-même.

Exemple de base

Nous ajoutons "orange" et "lemon" au début de $fruits. Les clés numériques sont réindexées automatiquement à partir de 0, et la valeur de retour 5 est le nouveau nombre d'éléments. La sortie est :

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

Gestion des clés

C'est la source de surprises la plus courante. array_unshift() traite les clés numériques et les clés string différemment :

• Les clés numériques sont réinitialisées. Toutes les clés entières existantes sont renumérotées à partir de 0. Toute clé entière personnalisée que vous avez définie est perdue.
• Les clés string (associatives) sont préservées. Seuls les éléments nouvellement ajoutés en tête reçoivent des clés numériques (0, 1, …) ; les clés string existantes conservent leurs noms.

<?php

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

?>

Sortie — notez que "name" est conservé, mais 10 et 20 deviennent 1 et 2 :

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

Quand l'utiliser

• Construction d'une file ou d'une liste où les nouveaux éléments appartiennent au début (le plus récent en premier).
• Ajout d'une ligne d'en-tête ou d'une valeur par défaut avant les données existantes.
• Annulation de l'effet de array_shift(), qui supprime le premier élément.

Une note sur les performances : étant donné que chaque élément existant doit être réindexé et décalé, array_unshift() est en O(n) — plus lent que array_push(), qui est en O(1). Pour de très grands arrays dans une boucle critique, préférez ajouter des éléments à la fin et inverser une seule fois à la fin, ou utilisez une structure comme SplDoublyLinkedList.

Fonctions associées

• array_push() — ajouter des éléments à la fin d'un array.
• array_shift() — supprimer le premier élément.
• array_splice() — insérer ou supprimer des éléments à n'importe quelle position.
• array_merge() — combiner deux arrays ou plus.

Pratique