array_splice()

Array manipulation is an essential part of programming, and PHP provides several built-in functions to help you work with arrays. One of the most flexible is array_splice — a single function that can remove, replace, and insert elements at any position. Unlike array_slice(), which copies a portion of an array and leaves the original untouched, array_splice modifies the array in place and returns whatever it removed.

This page explains the function signature, how each parameter behaves (including the often-confusing negative offsets and the way keys are renumbered), and shows runnable examples for the three things you'll actually use it for: removing, replacing, and inserting.

What is the array_splice function?

The array_splice function is a PHP built-in function that allows you to remove or replace elements from an array and add new elements in their place. The function modifies the original array and returns the removed elements, if any. The function takes three mandatory parameters and two optional parameters:

PHP array_splice function syntax

array_splice(array &$input, int $offset, ?int $length = null, mixed $replacement = [])

• $input: The input array that will be modified
• $offset: The index at which to start the operation
• $length (optional): The number of elements to remove. If not specified, all elements from the $offset to the end of the array will be removed
• $replacement (optional): The elements to be inserted in place of the removed elements. If not specified, no elements will be inserted

How does the array_splice function work?

The array_splice function operates on the input array, starting at the specified offset, and removes the specified number of elements. If no length is specified, all elements from the offset to the end of the array will be removed. The removed elements are returned as an array.

If the $replacement parameter is specified, the function inserts the replacement elements in place of the removed elements. The replacement elements can be of any data type, including arrays. If the $replacement parameter is not specified, no elements are inserted, and the function simply removes the specified elements.

The function modifies the input array in place, which means that the original array is changed by the operation. Because the first parameter is passed by reference (&$input), you must pass an actual variable — you cannot splice a literal array or the result of another function call directly.

Negative offset and length

Both $offset and $length accept negative values, which are counted from the end of the array:

• A negative $offset starts the operation that many elements from the end. array_splice($arr, -2) removes the last two elements.
• A negative $length stops the removal that many elements before the end of the array, so those trailing elements are kept. array_splice($arr, 1, -1) removes everything except the first and last element.

How keys are affected

array_splice is built for sequential (list-like) arrays. After the operation, numeric keys are always renumbered from 0, while string keys are preserved. If you need to keep numeric keys intact, array_splice is the wrong tool — reach for array_slice() with its preserve_keys flag instead.

Examples

Removing elements from an array

Suppose we have an array of numbers, and we want to remove the first three elements from the array. We can use the array_splice function as follows:

PHP Removing elements from an array using array_splice

In this example, the $numbers array will be modified, and the first three elements will be removed. The removed elements will be returned in the $removed variable. The value of $numbers after the function call will be [4, 5, 6], and the value of $removed will be [1, 2, 3].

Replacing elements in an array

Suppose we have an array of names, and we want to replace the third and fourth names with new names. We can use the array_splice function as follows:

PHP Replacing elements in an array using array_splice

In this example, the $names array will be modified, and the third and fourth names will be replaced with the names 'Alex' and 'Olivia'. The value of $names after the function call will be ['John', 'Mary', 'Alex', 'Olivia', 'Sarah']. Notice that the number of replacements does not have to match the number of removed elements — you can replace two elements with five, or with none.

Inserting elements into an array

Suppose we have an array of letters, and we want to insert the letters 'B' and 'C' at the beginning of the array. We can use the array_splice function as follows:

PHP Inserting elements into an array using array_splice

In this example, the $letters array will be modified, and the letters 'B' and 'C' will be inserted at the beginning of the array. The value of $letters after the function call will be ['B', 'C', 'D', 'E', 'F'].

Using negative offset and length

This example removes everything between the first and last element by combining a positive offset with a negative length:

PHP array_splice with a negative length

<?php

$items = ['first', 'a', 'b', 'c', 'last'];
$removed = array_splice($items, 1, -1);

print_r($items);   // ['first', 'last']
print_r($removed); // ['a', 'b', 'c']
?>

Here $offset is 1 (start after 'first') and $length is -1 (stop one element before the end, keeping 'last'), so the three middle elements are removed and returned.

Related functions

array_splice overlaps with several narrower array functions. Pick the most specific one for the job — it makes your intent clearer:

• array_slice() — extract a portion without modifying the original array.
• array_merge() — combine arrays end to end rather than at a specific position.
• array_push() / array_unshift() — append or prepend elements.
• array_pop() / array_shift() — remove a single element from the end or the start.

Conclusion

array_splice is the Swiss-army knife of array editing in PHP: one call can remove, replace, or insert elements at any offset. Keep these points in mind:

• It mutates the input array and returns the removed elements.
• The replacement count is independent of the removal count.
• Numeric keys are renumbered; string keys are kept.
• Negative $offset and $length count from the end of the array.

When you only need to read a slice without changing the source, prefer array_slice().

Practice