PHP array_splice() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Array

Definition

In PHP, array_splice() removes items from an array and can insert new items in their place.

It changes the original array and returns the items it removed. With a length of 0 it works as a pure insert.

Syntax

Call array_splice() with the values you need. Start with this line.

PHP
$removed = array_splice($colors, 1, 1);
CallWhat it does
array_splice($colors, 1, 1)Removes one item at position 1.
array_splice($colors, 1, 0, ["yellow"])Inserts "yellow" at position 1 without removing anything.
array_splice($nums, 1, 3, ["x"])Replaces three items with one.

array_splice() is the Swiss Army knife for editing a list in place: remove, insert and replace all use the same function. For a read-only copy of part of an array, use array_slice().

Library declarations
PHP
array_splice(array &$array, int $offset, ?int $length = null, mixed $replacement = []): array

Parameters

ParameterDescription
arrayRequired. The array to change. It is passed by reference.
offsetRequired. Where to start. A negative number counts from the end.
lengthOptional. How many items to remove. null (the default) removes everything from the offset to the end. 0 removes nothing.
replacementOptional. A value or an array of values to insert at the offset.

Return Value

Return ValueDescription
arrayAn array containing the removed items. It is empty if nothing was removed.

PHP Examples

Example 1 — Remove an Item

Remove the second color from a list.

PHP
<?php
$colors = ["red", "green", "blue"];
$removed = array_splice($colors, 1, 1);

echo "Removed: ", implode(", ", $removed), PHP_EOL;
echo "Left: ", implode(", ", $colors), PHP_EOL;

How It Works

  1. Create a list with three colors.
  2. Offset 1 and length 1 mean: remove one item starting at position 1.
  3. The removed item ("green") is returned in a new array.
  4. The original array now holds only "red" and "blue".

Example 2 — Insert Without Removing

Use a length of 0 to insert items and keep everything else.

PHP
<?php
$colors = ["red", "green", "blue"];
$removed = array_splice($colors, 1, 0, ["yellow"]);

echo implode(", ", $colors), PHP_EOL;
echo "Removed count: ", count($removed), PHP_EOL;

How It Works

  1. Offset 1 with length 0 means: go to position 1 but remove nothing.
  2. The replacement array ["yellow"] is inserted at that position.
  3. The old items after position 1 shift to the right.
  4. Nothing was removed, so the returned array has a count of 0.

Example 3 — Replace Several Items

Swap a group of items for something new.

PHP
<?php
$nums = [1, 2, 3, 4, 5];
$removed = array_splice($nums, 1, 3, ["x"]);

echo implode(", ", $nums), PHP_EOL;
echo implode(", ", $removed), PHP_EOL;

How It Works

  1. Start with the numbers 1 to 5.
  2. Offset 1 and length 3 select the values 2, 3 and 4.
  3. Those three items are replaced by the single value "x".
  4. $nums becomes 1, x, 5 and the removed values 2, 3, 4 are returned.

Frequently Asked Questions

It removes a range of items from an array and optionally inserts new items there. It changes the original array.
Use array_splice($array, $position, 0, [$item]). The 0 means nothing is removed.
array_slice() returns a copy of part of an array. array_splice() edits the original and returns what it removed.
Numeric keys are renumbered. String keys in the original array are kept.
Yes. A non-array value is treated as a one-item array. Wrap arrays in another array if you want to insert an array as one item.

Next: array_sum()

array_sum() adds up all the values in an array and returns the total.

array_sum() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful