PHP array_push() : ajouter des éléments à un tableau

array_push($arr, $value) ajoute une valeur à la fin d'un tableau. Pour une seule valeur, le raccourci $arr[] = $value; fait le même travail sans appel de fonction, et c'est ce qu'utilise la plupart du code PHP. Les deux modifient le tableau sur place.

<?php
$colors = ['red', 'green'];

$colors[] = 'blue';                    // shorthand, one value
array_push($colors, 'yellow', 'pink'); // several values at once

print_r($colors);

array_push() prend le tableau par référence, elle modifie donc la variable que vous passez. Elle renvoie le nouveau nombre d'éléments, que vous pouvez ignorer.

array_push ou $arr[] =

Utilisez $arr[] = $value pour une seule valeur : c'est plus court et cela évite un appel de fonction, ce qui compte dans une grosse boucle. Utilisez array_push() quand vous avez plusieurs valeurs à ajouter en une instruction, ou une liste de valeurs à décomposer.

<?php
$log = [];
for ($i = 1; $i <= 3; $i++) {
    $log[] = "step $i";
}

$more = ['step 4', 'step 5'];
$count = array_push($log, ...$more);   // spread a list in

print_r($log);
echo "Now $count entries\n";

$arr[] = fonctionne aussi sur une variable qui n'existe pas encore : PHP crée le tableau. array_push() exige un tableau existant : sur une variable non définie, elle lève TypeError: array_push(): Argument #1 ($array) must be of type array, null given.

Ajouter une clé et une valeur

array_push() n'ajoute que des valeurs avec la clé entière suivante. Pour ajouter une clé nommée, affectez-la. Pour ajouter plusieurs paires à la fois, utilisez += (garde les clés existantes) ou array_merge() (laisse les nouvelles valeurs l'emporter).

<?php
$user = ['name' => 'Ada'];

$user['email'] = 'ada@example.com';             // one key and value
$user += ['role' => 'admin', 'name' => 'X'];    // adds role; name already exists, kept

print_r($user);

array_push($user, 'oops');                      // gets key 0, not a name
print_r($user);

La différence entre + et array_merge() quand les clés se chevauchent est expliquée sur la page array_merge.

Ajouter au début : array_unshift

array_unshift($arr, $value) insère au début. Les clés entières sont renumérotées pour que la nouvelle valeur reçoive l'index 0 ; les clés de type chaîne restent telles quelles. Comme array_push(), elle accepte plusieurs valeurs et renvoie le nouveau nombre d'éléments.

<?php
$queue = ['Linus', 'Grace'];
array_unshift($queue, 'Ada');
print_r($queue);

$menu = ['home' => '/', 'about' => '/about'];
array_unshift($menu, '/login');      // string keys are kept, the new value gets key 0
print_r($menu);

Pour placer une paire nommée en premier, construisez un nouveau tableau : $menu = ['login' => '/login'] + $menu;.

Insérer à une position précise

array_splice($arr, $offset, 0, $values) insère sans rien supprimer : elle commence à $offset, supprime 0 élément et place les nouvelles valeurs à cet endroit. Les clés entières après le point d'insertion sont renumérotées.

<?php
$letters = ['a', 'b', 'd', 'e'];

array_splice($letters, 2, 0, 'c');           // insert 'c' at index 2
print_r($letters);

array_splice($letters, 1, 0, ['x', 'y']);    // insert two values at index 1
echo implode(' ', $letters), "\n";

array_splice() peut aussi supprimer et remplacer des éléments ; la page sur la suppression d'éléments montre ces formes.

Ajouter un autre tableau

array_push($a, $b) ajoute $b comme un seul élément imbriqué, ce qui est rarement voulu. Pour ajouter les valeurs de $b une par une, décomposez-les, ou construisez un nouveau tableau avec la syntaxe de décomposition ou array_merge().

<?php
$a = [1, 2];
$b = [3, 4];

$nested = $a;
array_push($nested, $b);       // [1, 2, [3, 4]]
echo json_encode($nested), "\n";

$flat = $a;
array_push($flat, ...$b);      // [1, 2, 3, 4]
echo json_encode($flat), "\n";

echo json_encode([...$a, ...$b]), "\n";

Erreur fréquente : affecter la valeur de retour

array_push() renvoie un nombre, le nouveau nombre d'éléments. Le réaffecter à la variable du tableau remplace votre tableau par un entier, et le prochain array_push() dessus lève une TypeError.

<?php
$items = ['pen', 'book'];

$result = array_push($items, 'lamp');
var_dump($result);    // the count, not the array

// Wrong: $items = array_push($items, 'mug');  turns $items into int(4)
array_push($items, 'mug');   // right: call it on its own line
print_r($items);

C'est pareil pour array_unshift() et pour sort(), qui renvoie true. Les fonctions qui modifient un tableau sur place renvoient un statut, pas le tableau.