Definition and Usage

PHP Version
4+

The array_push() function adds one or more elements to the end of an array—essentially "pushing" them onto it, like stacking items. This also increases the array's length.

This function does not return a new array; instead, it modifies the original array directly.
Additionally, it returns an integer representing the array's new length after the elements have been added.

Basic Example

PHP 
$array = [1, 2, 3];

// Add a single element to the end of the array
array_push($array, 4);
print_r($array);
/*
Output:
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
    )
*/

// Add multiple elements to the end of the array
array_push($array, 5, 6, 7);
print_r($array);
/*
Output:
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
        [4] => 5
        [5] => 6
        [6] => 7
    )
*/

Syntax

PHP 
array_push(array &$array, mixed $value1 [, mixed $value2 [, mixed $... ]]): int

Parameters

Parameters of the array_push() Function
&$array The array to which the values will be added.
$value1, $value2, $... One or more values to add to the end of the array.

Return Values

The return value represents the total number of elements in the array after the new elements have been added. This value is returned as an integer (e.g., 1, 2, 3, ...).

PHP 
$array = [1, 2, 3];

// Add a new element to the end of the array and store the return value
$total_elements = array_push($array, 4);
print_r($array);
/*
Output:
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
    )
*/

echo "Total number of elements in the array: " . $total_elements;
// Output: Total number of elements in the array: 4

Practical Examples

Here are some examples of how to use the array_push() function.

Adding Multiple Elements

To add multiple elements to an array, simply pass them as separate arguments to the array_push() function, separated by commas.

PHP 
$fruits = ['apple', 'banana', 'cherry'];

// Add elements to the end of the array
array_push($fruits, 'date', 'elderberry');

// Print the updated array
print_r($fruits);

/*
Output:
    Array
    (
        [0] => apple
        [1] => banana
        [2] => cherry
        [3] => date
        [4] => elderberry
    )
*/

Using the Array Append Operator Instead

Instead of using array_push(), you can also add elements to the end of an array using the array append operator []. The above example can be rewritten as follows:

PHP 
$fruits = ['apple', 'banana', 'cherry'];

// Add elements to the end of the array
$fruits[] = 'date';
$fruits[] = 'elderberry';

// Print the updated array
print_r($fruits);

/*
Output:
    Array
    (
        [0] => apple
        [1] => banana
        [2] => cherry
        [3] => date
        [4] => elderberry
    )
*/

Both methods can be used to append values to the end of an array. The choice between them often comes down to personal preference.

Avoid Using array_push() with Associative Arrays

Associative arrays are a powerful data structure in PHP that store data as key-value pairs. In some situations, you may need to add new data to an associative array. But is it appropriate to use the array_push() function for this purpose? In this section, we'll explore the limitations of using array_push() with associative arrays and introduce better alternatives.

Why array_push() Doesn't Fit

Since associative arrays rely on unique keys for each element, array_push() is not a good fit. This function is designed to add values to the end of an indexed array, not to assign values with specific keys. Using it with an associative array leads to unexpected results.

Adding Data to an Associative Array

Let's take a look at an example that demonstrates the problem with using array_push() on an associative array:

PHP 
$person = array(
    'first_name' => 'John',
    'last_name' => 'Doe',
    'age' => 30
);

// Attempting to add key-value pairs using array_push()
array_push($person, 'email', 'john@example.com', 'city', 'New York');

// Output the array
print_r($person);

/*
Output:
    Array
    (
        [first_name] => John
        [last_name] => Doe
        [age] => 30

        // These entries were added as numeric keys, not key-value pairs
        [0] => email
        [1] => john@example.com
        [2] => city
        [3] => New York
    )
*/

In the example above, using array_push() added the values to the array, but they were assigned numeric keys (0, 1, 2, 3) instead of becoming proper key-value pairs. This approach is uncommon and discouraged when working with associative arrays.

Important:
You cannot add a key-value pair to an associative array using array_push(). It only appends values and automatically assigns numeric keys.

To properly add data to an associative array, you should assign values directly by specifying the key:

PHP 
$person = array(
    'first_name' => 'John',
    'last_name' => 'Doe',
    'age' => 30
);

// Add a new key-value pair
$person['address'] = 'Seoul, Korea';

// Output the updated array
print_r($person);

/*
Output:
    Array
    (
        [first_name] => John
        [last_name] => Doe
        [age] => 30
        [address] => Seoul, Korea
    )
*/

This is the standard and recommended way to add data to an associative array in PHP.

Conclusion

The array_push() function is intended for use with indexed arrays and does not work correctly with associative arrays. When you need to add data to an associative array, always assign the value directly using the appropriate key. This approach ensures better control over the data structure and improves code readability and maintainability.

In summary, indexed arrays and associative arrays serve different purposes, and understanding the distinction is key to choosing the right structure for your data.

References

See also