PHP array_pad() Function: Usage and Examples

Sometimes a PHP array contains fewer elements than your application needs. For example, you might want to display a fixed number of items, add placeholders to a list, or prepare data for a specific format.

The array_pad() function extends an existing array by adding a specified value until it reaches the required length.

What Is array_pad() in PHP?

The array_pad() function adds elements to the beginning or end of an array until it reaches a specified number of elements.

Its syntax is:

array_pad(
    array $array,
    int $length,
    mixed $value
): array

The parameters are:

• $array — The original array to extend.
• $length — The target number of elements. Its sign determines which side receives the new elements.
• $value — The value assigned to each added element.

The function returns a new array. It does not modify the original array.

Example 1: Adding Values to the End

A positive length adds elements to the end of the array.

<?php

$numbers = [10, 20, 30];

$result = array_pad($numbers, 5, 0);

print_r($result);

Output:

Array
(
    [0] => 10
    [1] => 20
    [2] => 30
    [3] => 0
    [4] => 0
)

The original array contains three elements. Since the target length is five, PHP adds two zeros.

Important: The second parameter specifies the final array length, not how many new elements to add.

Example 2: Adding Values to the Beginning

A negative length adds elements to the beginning of the array.

<?php

$numbers = [10, 20, 30];

$result = array_pad($numbers, -5, 0);

print_r($result);

Output:

Array
(
    [0] => 0
    [1] => 0
    [2] => 10
    [3] => 20
    [4] => 30
)

The target length is five, and the negative sign tells PHP to add the two missing elements before the existing values.

Negative lengths do not create negative indexes automatically.

What Happens If the Array Is Already Long Enough?

The array_pad() function never removes elements.

If the array already contains at least the requested number of elements, PHP returns it without adding anything.

<?php

$colors = ["Red", "Green", "Blue"];

$result = array_pad($colors, 2, "Empty");

print_r($result);

Output:

Array
(
    [0] => Red
    [1] => Green
    [2] => Blue
)

The array still contains three elements because array_pad() does not truncate data.

If you need to limit an array to a specific number of elements, consider array_slice() instead.

Working with Array Keys

When padding occurs, PHP reindexes numeric keys but preserves string keys.

<?php

$data = [
    "name" => "Alex",
    10 => "Editor"
];

$result = array_pad($data, 4, "Unknown");

print_r($result);

Output:

Array
(
    [name] => Alex
    [0] => Editor
    [1] => Unknown
    [2] => Unknown
)

The string key name remains unchanged, but the numeric key 10 is reassigned.

Also, array_pad() does not fill gaps in existing numeric indexes. It adds elements based on the total element count, not missing key numbers.

Practical Example: Creating a Fixed-Size Participant List

Imagine you're building an application that displays four participant slots for each training session.

Some sessions have fewer than four registered participants. You want the remaining slots to display "Available spot".

Create a file named participants.php:

<?php

declare(strict_types=1);

// Registered participants.

$participants = [
    "Alex",
    "Taylor"
];

// Display four participant slots.

$slots = array_pad(
    $participants,
    4,
    "Available spot"
);

echo "<h2>Session Participants</h2>";
echo "<ol>";

foreach ($slots as $participant) {

    echo "<li>" . htmlspecialchars(
        $participant,
        ENT_QUOTES,
        "UTF-8"
    ) . "</li>";
}

echo "</ol>";

Browser output:

Session Participants

1. Alex
2. Taylor
3. Available spot
4. Available spot

The function adds two placeholders, bringing the total number of elements to four.

If a session already has four participants, nothing is added. If it has more than four, the additional participants remain in the result.

This approach is useful for fixed-size displays, placeholder values, and preparing collections that require a minimum number of elements.

array_pad() vs array_fill() vs array_slice()

Use array_pad() when you want to keep existing elements and add default values until the array reaches a minimum length.

Common Mistakes

• Confusing length with additional elements: The second argument specifies the target total length.
• Expecting a negative length to create negative keys: A negative length controls padding direction.
• Expecting the array to shrink: array_pad() never removes existing elements.
• Assuming numeric keys are preserved: Padding can reindex numeric keys.
• Requesting excessively large arrays: Very large target lengths can consume substantial memory. Before PHP 8.3, a single call was also limited to adding 1,048,576 elements.

Key Takeaways

• array_pad() extends an array to a specified minimum length.
• Positive lengths add values at the end; negative lengths add them at the beginning.
• The third parameter determines the padding value.
• Existing elements are never removed.
• The function returns a new array without modifying the original.
• Numeric keys can be reindexed when padding occurs.

The array_pad() function is a convenient way to extend PHP arrays with default values. It is especially useful when preparing fixed-size collections, adding placeholders, and maintaining consistent data formats.

For additional details, see the official PHP array_pad() documentation.