Laravel Collection Public API: splice

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)

∎