array_push
Appends one or more values to the end of an array and returns the new element count.
array_push(array &$array, mixed ...$values): int- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The array to append to. Passed by reference and modified in place. |
$valuesoptional | mixed | Any number of values to append, in order. Each becomes one element. |
Return value
intThe number of elements in the array after the values have been appended.
Errors
Throws a TypeError if the first argument is not an array, and an error if it is not a variable, since the parameter is by reference.
Changelog
- PHP 7.3.0Can now be called with only the array argument; previously at least one value was required.
array_push() appends values to the end of an array, in place, and returns how many elements the array now holds. Each argument becomes exactly one element.
When to use it and when not to
For a single value, $array[] = $value; does the same thing and is faster, because it avoids a function call entirely. array_push() earns its place when you are appending several values at once, or when you want the resulting count as an expression without a separate count() call.
How keys are assigned
Appended values get the next free integer key — one above the highest integer key currently in the array, regardless of what string keys exist. So pushing onto ['x' => 1, 5 => 'five'] creates key 6. If the array has no integer keys at all, the first pushed value gets key 0.
What trips people up
Pushing an array pushes it as a single nested element, not as its contents. To append the contents, spread it — array_push($a, ...$b) — or use array_merge(). And because the first parameter is by reference, you cannot push onto a function's return value; assign it to a variable first.
Since PHP 7.3 calling it with just the array is legal and simply does nothing, which is handy when spreading a possibly-empty list.
Example
When to use it
- Collect validation error messages as each rule fails
- Append several parsed rows to a results buffer in one call
- Build a breadcrumb trail while walking a tree
- Add multiple query parameters to a list before imploding them
Frequently asked questions
Is array_push faster than $array[] = $value?
No — for a single value, $array[] = $value is faster because it avoids a function call. array_push is worth using when appending several values in one statement or when you need the new count returned.
How do I push all elements of one array into another?
Use the spread operator: array_push($target, ...$source). Passing $source directly would append it as a single nested element instead.
What key does array_push assign to a new element?
The next free integer key, which is one above the highest existing integer key — string keys are ignored when computing it. An array with no integer keys gets key 0 for the first pushed value.
More examples
Collecting validation errors
Each failing rule appends one message, giving a two-element list. For a single value like this, $errors[] = '...' would be equivalent and marginally faster — array_push pays off when several messages go in at once.
<?php
$input = ['name' => '', 'email' => 'nope'];
$errors = [];
if ($input['name'] === '') {
array_push($errors, 'name is required');
}
if (!str_contains($input['email'], '@')) {
array_push($errors, 'email is invalid');
}
print_r($errors);
echo count($errors), " problem(s)\n";Nested versus spread
The first result is [1, 2, [3, 4]] — the array went in as a single element. The second is [1, 2, 3, 4] because the spread operator turned each item into its own argument. This is the most common array_push mistake.
<?php
$b = [3, 4];
$nested = [1, 2];
array_push($nested, $b);
print_r($nested);
$flat = [1, 2];
array_push($flat, ...$b);
print_r($flat);Pushing nothing is allowed
Since PHP 7.3 the values argument is optional, so spreading an empty array is a no-op returning the unchanged count of 2. On older versions this was an ArgumentCountError.
<?php
$extra = [];
$list = ['a', 'b'];
$n = array_push($list, ...$extra);
echo "count: $n\n";
print_r($list);
Discussion