array_fill()

Purpose

array_fill() builds a new array that contains the same value repeated a fixed number of times. You choose the first key, the number of elements and the value. Typical uses are creating a row of zero counters, a placeholder list, or a blank grid that you update later.

The keys are always consecutive integers. If you need arbitrary or string keys, use array_fill_keys() instead.

Signature

Parameters

• $start_index: the key of the first element. The following keys increase by one. The value can be positive, zero or negative.
• $count: how many elements to create. It must be at least 0 and at most 2147483647. There is no default.
• $value: the value stored in every element. It can be any type, including arrays and objects.

None of the parameters are optional, so you must supply all three.

Return value and failures

The function returns the filled array. With $count set to 0 it returns an empty array. If $count is outside the allowed range, PHP 8 throws a ValueError. The manual notes that before PHP 8.0.0 this situation raised a warning and returned false. Modern code does not need to check for false. Catch the exception only if the count comes from untrusted input. In practice, a very large count will exhaust memory long before it reaches the documented limit, so validate sizes yourself.

Example 1: a basic fill

The keys start at 5 and count upward. Because they do not begin at 0, json_encode() writes the array as an object. A count of zero gives an empty list.

<?php
$flags = array_fill(5, 3, 'x');
echo json_encode($flags, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";
echo json_encode(array_fill(3, 0, 'x'), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"5":"x","6":"x","7":"x"}
[]

Example 2: a negative start index

In PHP 8 negative keys continue normally. Starting at -2 with four elements produces the keys -2, -1, 0 and 1. Older PHP 7 code behaved differently, because the key after a negative start jumped to zero. Do not rely on that older behavior.

<?php
$values = array_fill(-2, 4, 'pear');
echo json_encode($values, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"-2":"pear","-1":"pear","0":"pear","1":"pear"}

Example 3: objects are shared

The value is evaluated once and then placed in every slot. Scalars and arrays are copied by value, so changing one array element later does not affect the others. Objects are different. Every slot holds the same object handle, so a change made through one slot is visible through all the others.

<?php
$items = array_fill(0, 2, new stdClass());
$items[0]->name = 'shared';
echo json_encode($items, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";
echo var_export($items[0] === $items[1], true), "\n";

[{"name":"shared"},{"name":"shared"}]
true

If each slot needs its own object, build the array with a loop and use new on each iteration.

Edge cases

• Non-list keys: a start index other than 0 gives an array that is not a list. json_encode() then outputs an object, and functions that expect a list may behave differently.
• Nested arrays: array_fill(0, 2, array_fill(0, 3, 0)) is a safe way to create a 2 by 3 grid. Each row is an independent copy once you assign into it.
• Mixed values: null, false and 0 are all valid fill values. The function does not skip any of them.
• Huge counts: the documented maximum is 2147483647, but memory limits will stop you much sooner.

Common mistakes

1. Swapping the first two arguments. The start index comes first and the count second. array_fill(3, 0, 'x') is empty, but array_fill(0, 3, 'x') has three elements.
2. Expecting a list after a non-zero start. If you need keys beginning at 0, pass 0, or call array_values() on the result.
3. Filling with one object and expecting copies. All entries refer to the same instance, as Example 3 shows.
4. Passing a negative count. This throws a ValueError in PHP 8. Clamp or validate the count first.
5. Checking for false. That was the old failure signal and no longer applies.
6. Expecting string keys. The keys are integers only. Use array_fill_keys() for named keys.

Related functions

• array_fill_keys() fills an array using keys you supply.
• str_repeat() repeats a string instead of building an array.
• range() creates a sequence of different values, rather than the same value repeated.
• array_pad() extends an existing array to a given length.

Recap

array_fill() takes a start index, a count and a value, and returns an array with consecutive integer keys. A count of zero gives an empty array, and an out-of-range count throws ValueError. Negative start indexes continue upward normally in PHP 8, and object values are shared by every element, not cloned.