array_pad()

Purpose

array_pad() makes sure an array has at least a given number of elements. If the array is too short, it returns a copy extended with a filler value. The sign of the requested length picks the side: a positive length pads on the right (the end), a negative length pads on the left (the start). It is useful for fixed-width rows, default slots and aligning lists before comparing or combining them.

Signature

Parameters

• $array: the source array. It is never modified, because PHP passes it by value and you receive a copy.
• $length: the target size. Its sign selects the side (positive = right, negative = left), and its absolute value is the size you want the result to reach. There is no default; you must supply it.
• $value: the filler placed in each new slot. It can be any type, including null, an array or an object. If it is an object, every slot holds a reference to the same object instance.

None of the three parameters is optional.

Return value and failure cases

The function returns a new array. If the absolute value of $length is less than or equal to the current element count, nothing is added and you get an unchanged copy. Otherwise the result has exactly abs($length) elements.

The function does not return false. Wrong argument types raise a TypeError. Per the changelog, before PHP 8.3 only 1048576 elements could be added in a single call; since 8.3 the limit is the maximum array size. A very large length can still exhaust memory, so validate lengths that come from user input.

Example 1: padding right, left and not at all

The first call pads on the right with zeros. The second uses a negative length to pad on the left. The third asks for a length smaller than the array, so nothing changes.

<?php
$input = [12, 10, 9];
echo json_encode(array_pad($input, 5, 0)), PHP_EOL;
echo json_encode(array_pad($input, -7, -1)), PHP_EOL;
echo json_encode(array_pad($input, 2, 'noop')), PHP_EOL;

[12,10,9,0,0]
[-1,-1,-1,-1,12,10,9]
[12,10,9]

Example 2: normalizing rows to a fixed width

When rows come from a parser, some may have missing trailing columns. Padding with null gives every row the same shape.

<?php
$rows = [['Ada', 'ada@example.com'], ['Linus'], []];
$normalized = array_map(fn(array $row): array => array_pad($row, 2, null), $rows);
echo json_encode($normalized, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), PHP_EOL;

[["Ada","ada@example.com"],["Linus",null],[null,null]]

Example 3: keys and the original array

String keys survive padding, but integer keys are renumbered in the result. The original variable is untouched.

<?php
$input = ['x' => 'a', 5 => 'b'];
$padded = array_pad($input, 4, 'z');
echo json_encode($padded), PHP_EOL;
echo json_encode($input), PHP_EOL;

{"x":"a","0":"b","1":"z","2":"z"}
{"x":"a","5":"b"}

In the padded result, the integer key 5 became 0, and the two new elements received keys 1 and 2. The string key x was kept.

Edge cases

• Length equals the size: no padding, a plain copy is returned.
• Length 0: the absolute value is never greater than the size, so you get the array back unchanged.
• Empty array: the result is $length copies of the filler.
• Negative padding and keys: with left padding the new values take the first integer positions, and the original integer-keyed elements follow after them, renumbered.
• Array filler: an array passed as $value is placed whole into each slot, not spread into separate elements.

Common mistakes

1. Expecting in-place change. array_pad($list, 5, 0); on its own line discards the result. Assign it: $list = array_pad($list, 5, 0);.
2. Treating length as a number to add. $length is the final size, not the count of extra elements. Padding a 3-element array with length 2 adds nothing.
3. Forgetting the sign. To pad at the start, use a negative length, for example -5. A positive length always pads at the end.
4. Relying on integer keys. If your array uses meaningful integer keys such as IDs, padding renumbers them. Use another approach, such as adding keys explicitly, when keys matter.
5. Using it to truncate. array_pad() never shortens an array. Use array_slice() for that.
6. Sharing one object filler. Padding with an object puts the same instance in every slot, so changing one changes them all.

Related functions

• array_fill() creates an array of repeated values from a start index.
• range() creates a sequence of numbers or characters.
• array_slice() extracts or truncates part of an array, the usual complement for fixed-length results.
• str_pad() offers the same idea for strings.

Recap

array_pad($array, $length, $value) returns a copy of the array grown to abs($length) elements. Positive lengths pad on the right and negative lengths pad on the left. Arrays already long enough come back unchanged, string keys are preserved, integer keys are renumbered, and you must use the returned array.