splice($offset, $length = null, $replacement = [])
The splice
method is a versatile method; it is often used to remove a portion of a collection and return the removed section. It defines three parameters: $offset
, $length
and $replacement
. The $offset
tells the splice
method where to begin when removing items from the collection. For example, if the $offset
is 3
, the all items beginning with the third item in the collection will be removed. If the $offset
is negative, items will be removed that are that distance from the end of the collection. The splice
method modifies the original Collection
instance and returns the removed items as a new Collection
instance.
The following example shows the basic usage of the splice
method:
1<?php
2
3use Illuminate\Support\Collection;
4
5// Create a new collection instance.
6$collection = new Collection([
7 0, 1, 2 ,3 , 4, 5, 6, 7 ,8
8]);
9
10// Splice the $collection starting with the third item.
11$spliced = $collection->splice(3);
After the above has executed, the $spliced
variable will be an instance of Collection
and contain a value similar to the following output:
1object(Illuminate\Support\Collection)[134]
2 protected 'items' =>
3 array (size=6)
4 0 => int 3
5 1 => int 4
6 2 => int 5
7 3 => int 6
8 4 => int 7
9 5 => int 8
The $collection
variable will also have been modified, and will now contain a value similar to the following output:
1object(Illuminate\Support\Collection)[133]
2 protected 'items' =>
3 array (size=3)
4 0 => int 0
5 1 => int 1
6 2 => int 2
The $length
parameter can be used to control how long the section that is removed from the collection can be. The following example demonstrates how to remove four items from the collection, starting with the third item:
1<?php
2
3use Illuminate\Support\Collection;
4
5// Create a new collection instance.
6$collection = new Collection([
7 0, 1, 2 ,3, 4 , 5, 6, 7 ,8
8]);
9
10// Splice the $collection starting with the third item
11// and take at most 4 items.
12$spliced = $collection->splice(3, 4);
After the above example has executed, the $spliced
variable will again be an instance of Collection
and contain a value similar to the following output:
1object(Illuminate\Support\Collection)[134]
2 protected 'items' =>
3 array (size=4)
4 0 => int 3
5 1 => int 4
6 2 => int 5
7 3 => int 6
Like before, the $collection
variable will have been modified and now contain a value similar to the following output:
1object(Illuminate\Support\Collection)[133]
2 protected 'items' =>
3 array (size=5)
4 0 => int 0
5 1 => int 1
6 2 => int 2
7 3 => int 7
8 4 => int 8
The $replacement
parameter can be utilized to replace the items removed from the collection. When using the $replacement
parameter, the items removed from the collection are still returned as a new instance of Collection
. Any argument passed for $replacement
must be an array, or must be able to be cast into an array. Any keys from the $replacement
array will not be preserved when added to the collection.
The following example shows how to use the $replacement
parameter:
1<?php
2
3use Illuminate\Support\Collection;
4
5// Create a new collection instance.
6$collection = new Collection([
7 'first', 'second', 'third', 'fourth'
8]);
9
10// Replace all items beginning with the second.
11$spliced = $collection->splice(1, 3, [
12 '2nd', '3rd', '4th'
13]);
After the above code has executed, the $spliced
variable will be an instance of Collection
and contain a value similar to the following output:
1object(Illuminate\Support\Collection)[134]
2 protected 'items' =>
3 array (size=3)
4 0 => string 'second' (length=6)
5 1 => string 'third' (length=5)
6 2 => string 'fourth' (length=6)
The $collection
variable will also have been modified, but instead of just removing items, the new items 2nd
, 3rd
and 4th
will have been inserted into the collection in place of the items that were removed:
1object(Illuminate\Support\Collection)[133]
2 protected 'items' =>
3 array (size=4)
4 0 => string 'first' (length=5)
5 1 => string '2nd' (length=3)
6 2 => string '3rd' (length=3)
7 3 => string '4th' (length=3)
∎