Laravel Collections – wrap() and unwrap() Methods

In this post, we will look at how wrap() and unwrap() methods can be used when dealing with Laravel Collections. This is a third part of Laravel Collections Series.

wrap() Method

As I discussed in previous post that the make() method create a new instance of a collection from an array. wrap() method is similar to make() method, except it will create a collection from any value supplied to it.

This function is very helpful where you have to make sure only the collection instance is expected.

Signature

Below is the signature of wrap() method defined in Illuminate\Support\Collection class.

/**
 * Wrap the given value in a collection if applicable.
 *
 * @param  mixed  $value
 * @return static
 */
public static function wrap($value)
{
    return $value instanceof self
        ? new static($value)
        : new static(Arr::wrap($value));
}

As you can see in the above signature, Laravel is checking if the value provided is an instance of Collection class, if it then returns a collection instance of the value, if not then convert the value to a new collection instance.

wrap() Method Example

For practical use, let’s go through with an example.

use App\Product;
use Illuminate\Support\Collection;

$product = new Product();
$products = Collection::wrap($product);

Above, we have created a new instance of Product model which will return the collection and then wrapped the product inside a new collection called products.

As wrap method will not wrap a value if the value is a collection, it can be used to make sure that function or method arguments are always a collection.

use Illuminate\Support\Collection;

function addProductsToOrder($products) {
    // Ensure that the products is always a collection.
    Collection::wrap($products)->each->addToOrder();
}

We can use the above function like below:

// By supplying a single product instance
$product = new Product();
addProductsToOrder($product);

// By supplying a collection of products
$products = Collection::wrap($product);
addProductsToOrder($products);

unwrap() Method

The unwrap() method is the opposite of wrap() method, if the provided value is already a collection, the collection’s underlying items will be returned. If not then the value will be returned as it is without modification.

Signature

Below is the signature of unwrap() method defined in Illuminate\Support\Collection class.

/**
 * Get the underlying items from the given collection if applicable.
 *
 * @param  array|static  $value
 * @return array
 */
public static function unwrap($value)
{
    return $value instanceof self ? $value->all() : $value;
}

unwrap() Method Example

use Illuminate\Support\Collection;

// Create a new collection of users

$users = collect([
    'Jhon', 'Mike', 'Sam', 'Thomas'
]);

// Get the collection items

$items = Collection::unwrap($users);

dd($items);
// [
  0 => "Jhon"
  1 => "Mike"
  2 => "Sam"
  3 => "Thomas"
]

As we checked in the wrap() method that the function or method arguments are always a collection, in unwrap() we can check that argument supplied to function is always an array.

That’s it for now. If you have any question please leave it in the comments box below.