array_splice
Removes a portion of an array in place and optionally replaces it with new elements.
array_splice(array &$array, int $offset, ?int $length = null, mixed $replacement = []): array- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The input array, passed by reference and modified in place. |
$offset | int | Where the removed portion starts. A negative offset counts back from the end. |
$lengthoptional | ?int= null | How many elements to remove. Null removes everything from offset to the end; a negative value stops that many elements before the end. |
$replacementoptional | mixed= [] | Values to insert in place of the removed portion. A non-array value is cast with (array), so a plain string or int works without wrapping. |
Return value
arrayAn array of the elements that were removed. Empty if nothing was removed.
Errors
Throws a TypeError if $array is not a referenceable array variable.
Changelog
- PHP 8.0length is nullable now, so you can pass null explicitly to remove through to the end while still supplying a replacement.
array_splice() is the editing counterpart of array_slice(). It cuts elements out of the array you pass in and hands back what it removed, optionally dropping new elements into the gap.
When to reach for it
Use it for insertion at a position — pass a length of 0 and the array shifts to make room. Use it to remove a range and keep the list packed, which unset() will not do. It is also the natural way to move an item in a reorderable list: splice it out, then splice it back in at the new index.
What trips people up
Numeric keys in both the array and the replacement are always renumbered. There is no preserve_keys flag, so array_splice() is for lists, not for id-keyed maps. String keys in the target array are kept, but keys in the replacement are discarded entirely.
The replacement is cast with (array). That is convenient for scalars but dangerous for objects and null: (array) $obj spreads the object's properties into the array, and (array) null is an empty array. Always wrap objects and nulls in [ ] yourself.
The return value is what was removed, not the modified array — a common mix-up that produces an empty result.
Example
When to use it
- Insert a row at a specific index in an ordered list without rebuilding the array.
- Remove a range of items and keep the remaining keys packed as a clean list.
- Move an element from one position to another in a drag-and-drop ordering.
Frequently asked questions
What is the difference between array_splice and array_slice?
array_splice modifies the array in place and returns the removed elements; array_slice returns a copy of a portion and leaves the original untouched.
How do I insert an element at a specific index in a PHP array?
Call array_splice($array, $index, 0, [$value]). A length of 0 removes nothing, so the value is inserted and everything after it shifts right.
Does array_splice preserve keys?
No. Integer keys in the array and all keys in the replacement are renumbered from 0. Use array_slice with preserve_keys if you need the original keys.
More examples
Moving an item to a new position
Prints usage, intro, setup, faq. Splicing with length 1 extracts the element as a one-item array, and splicing with length 0 inserts it without removing anything.
<?php
$order = ['intro', 'setup', 'usage', 'faq'];
$moved = array_splice($order, 2, 1); // pull out 'usage'
array_splice($order, 0, 0, $moved); // put it at the front
print_r($order);Truncating from an offset
Omitting length removes everything from index 3 to the end. $history keeps h1, h2, h3 and $dropped holds h4, h5.
<?php
$history = ['h1', 'h2', 'h3', 'h4', 'h5'];
$dropped = array_splice($history, 3);
print_r($history);
print_r($dropped);
echo count($history), " kept\n";Wrap objects and null in an array
The first splice inserts nothing because null casts to an empty array. Wrapping it in [] inserts a real null value. The same trap applies to objects, whose properties would otherwise be spread out as separate elements.
<?php
$a = ['x', 'y'];
array_splice($a, 1, 0, null); // (array) null is empty - nothing inserted
print_r($a);
$b = ['x', 'y'];
array_splice($b, 1, 0, [null]); // explicit array - null is inserted
var_dump($b);
Discussion