Функция array_push в PHP: подробное руководство

array_push() добавляет один или несколько элементов в конец array, работая с ним как со стеком. Это стандартный способ расширить список в PHP: функция возвращает новое количество элементов после добавления значений.

На этой странице рассматриваются синтаксис, возвращаемое значение array_push(), поведение с ассоциативными и пустыми array, более быстрый синтаксис [], а также связанные функции для удаления или добавления элементов в начало.

Синтаксис

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

• $array — array для изменения. Передаётся по ссылке (&), поэтому исходная переменная изменяется на месте без повторного присваивания.
• $values — одно или несколько значений для добавления в конец, в указанном порядке.
• Возвращаемое значение — новая длина array (целое число).

Базовый пример

В примере ниже начинаем с трёх фруктов и добавляем ещё два:

Новые значения добавляются по порядку, а $count содержит обновлённую длину:

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

Сокращённый синтаксис [] для одного значения

Если нужно добавить только один элемент, синтаксис $array[] = $value делает то же самое и работает быстрее, поскольку исключает накладные расходы на вызов функции:

<?php

$colors = array("red", "green");
$colors[] = "blue"; // same as array_push($colors, "blue")
print_r($colors);

?>

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

Используйте array_push(), когда нужно добавить несколько значений одновременно; для одного значения применяйте [].

Поведение с ключами

array_push() всегда переиндексирует добавляемые значения новыми целочисленными ключами, продолжая от наибольшего существующего целочисленного ключа. Существующие строковые (ассоциативные) ключи остаются нетронутыми:

<?php

$data = array("name" => "Ann", 5 => "five");
array_push($data, "added");
print_r($data);

?>

Array
(
    [name] => Ann
    [5] => five
    [6] => added
)

Обратите внимание: новый элемент получил индекс [6] — на единицу больше наибольшего целочисленного ключа (5), а не [2].

Добавление в пустой array

Объявлять ключи заранее не нужно. При добавлении в пустой array нумерация начинается с 0:

<?php

$list = array();
array_push($list, "first", "second");
print_r($list);

?>

Array
(
    [0] => first
    [1] => second
)

Частые ошибки

• Изменение на месте. Поскольку array передаётся по ссылке, не пишите $arr = array_push($arr, $x) — это перезапишет ваш array целочисленной длиной. Вызывайте array_push($arr, $x) в отдельной строке.
• Аргумент должен быть переменной. Так как параметр передаётся по ссылке, нельзя добавить элемент в литерал вроде array_push(array(), "x").
• Используйте [] для одного значения. Для одного элемента $arr[] = $value нагляднее и чуть быстрее.

Связанные функции

• array_pop() — удаляет и возвращает последний элемент (противоположность добавления).
• array_unshift() — добавляет элементы в начало array.
• array_shift() — удаляет первый элемент.
• array_merge() — объединяет два или более array в один.
• array_splice() — вставляет или удаляет элементы в любой позиции.

Практика