Collections

Create and work with collections of data objects using arrays, Laravel collections, and paginators.

It is possible to create a collection of data objects by using the collect method:

SongData::collect([
    ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
    ['title' => 'Giving Up on Love', 'artist' => 'Rick Astley'],
]); // returns an array of SongData objects

Whatever type of collection you pass in, the package will return the same type of collection with the freshly created data objects within it. As long as this type is an array, Laravel collection or paginator or a class extending from it.

Working with Eloquent Collections

This opens up possibilities to create collections of Eloquent models:

SongData::collect(Song::all()); // return an Eloquent collection of SongData objects

Working with Paginators

Or use a paginator:

SongData::collect(Song::paginate()); // return a LengthAwarePaginator of SongData objects

// or

SongData::collect(Song::cursorPaginate()); // return a CursorPaginator of SongData objects

Internally the from method of the data class will be used to create a new data object for each item in the collection.

Collections Already Containing Data Objects

When the collection already contains data objects, the collect method will return the same collection:

SongData::collect([
    SongData::from(['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley']),
    SongData::from(['title' => 'Giving Up on Love', 'artist' => 'Rick Astley']),
]); // returns an array of SongData objects

Type Transformation

The collect method also allows you to cast collections from one type into another. For example, you can pass in an array and get back a Laravel collection:

SongData::collect($songs, Collection::class); // returns a Laravel collection of SongData objects

This transformation will only work with non-paginator collections.

Magically Creating Collections

We’ve already seen that from can create data objects magically. It is also possible to create a collection of data objects magically when using collect.

Let’s say you’ve implemented a custom collection class called SongCollection:

class SongCollection extends Collection
{
    public function __construct(
        $items = [],
        public array $artists = [],
    ) {
        parent::__construct($items);
    }
}

Since the constructor of this collection requires an extra property it cannot be created automatically. However, it is possible to define a custom collect method which can create it:

class SongData extends Data
{
    public string $title;
    public string $artist;

    public static function collectArray(array $items): SongCollection
    {
        return new SongCollection(
            parent::collect($items),
            array_unique(array_map(fn(SongData $song) => $song->artist, $items))
        );
    }
}

Now when collecting an array data objects a SongCollection will be returned:

SongData::collectArray([
    ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
    ['title' => 'Living on a prayer', 'artist' => 'Bon Jovi'],
]); // returns an SongCollection of SongData objects

Requirements for Magical Collection Methods

There are a few requirements for this to work:

• The method must be static
• The method must be public
• The method must have a return type
• The method name must start with collect
• The method name must not be collect

Creating a Data Object with Collections

You can create a data object with a collection of data objects just like you would create a data object with a nested data object:

use App\Data\SongData;
use Illuminate\Support\Collection;

class AlbumData extends Data
{    
    public string $title;
    /** @var Collection<int, SongData> */
    public Collection $songs;
}

AlbumData::from([
    'title' => 'Never Gonna Give You Up',
    'songs' => [
        ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
        ['title' => 'Giving Up on Love', 'artist' => 'Rick Astley'],
    ]
]);

Since the collection type here is a Collection, the package will automatically convert the array into a collection of data objects.

DataCollections, PaginatedDataCollections and CursorPaginatedCollections

The package also provides a few collection classes which can be used to create collections of data objects. It was a requirement to use these classes in the past versions of the package when nesting data objects collections in data objects. This is no longer the case, but there are still valid use cases for them.

You can create a DataCollection like this:

use Spatie\LaravelData\DataCollection;

SongData::collect(Song::all(), DataCollection::class);

A PaginatedDataCollection can be created like this:

use Spatie\LaravelData\PaginatedDataCollection;

SongData::collect(Song::paginate(), PaginatedDataCollection::class);

And a CursorPaginatedCollection can be created like this:

use Spatie\LaravelData\CursorPaginatedCollection;

SongData::collect(Song::cursorPaginate(), CursorPaginatedCollection::class);

Transforming paginated collection items

Both PaginatedDataCollection and CursorPaginatedDataCollection support the through() method to transform items in the collection:

$paginatedPosts = PostData::collect($posts->paginate(10));

// Transform each item in the paginated collection
$transformedPosts = $paginatedPosts->through(function (PostData $post) {
    return new EnrichedPostData(
        ...$post->toArray(),
        view_count: $post->calculateViews(),
    );
});

The through() method returns a new collection with transformed items while preserving pagination information.

This works identically for both PaginatedDataCollection (using paginate()) and CursorPaginatedDataCollection (using cursorPaginate()).

Why Use These Collection Classes?

We advise you to always use arrays, Laravel collections and paginators within your data objects. But let’s say you have a controller like this:

class SongController
{
    public function index()
    {
        return SongData::collect(Song::all());    
    }
}

In the next chapters of this documentation, we’ll see that it is possible to include or exclude properties from the data objects like this:

class SongController
{
    public function index()
    {
        return SongData::collect(Song::all(), DataCollection::class)->include('artist');    
    }
}

This will only work when you’re using a DataCollection, PaginatedDataCollection or CursorPaginatedCollection.

DataCollection Methods

DataCollections provide some extra functionalities like:

// Counting the amount of items in the collection
count($collection);

// Changing an item in the collection
$collection[0]->title = 'Giving Up on Love';

// Adding an item to the collection
$collection[] = SongData::from(['title' => 'Never Knew Love', 'artist' => 'Rick Astley']);

// Removing an item from the collection
unset($collection[0]);

It is even possible to loop over it with a foreach:

foreach ($songs as $song){
    echo $song->title;
}

The DataCollection class implements a few of the Laravel collection methods:

• through
• map
• filter
• first
• each
• values
• where
• reduce
• sole

You can, for example, get the first item within a collection like this:

SongData::collect(Song::all(), DataCollection::class)->first(); // SongData object

The collection Method

In previous versions of the package it was possible to use the collection method to create a collection of data objects:

SongData::collection(Song::all()); // returns a DataCollection of SongData objects
SongData::collection(Song::paginate()); // returns a PaginatedDataCollection of SongData objects
SongData::collection(Song::cursorPaginate()); // returns a CursorPaginatedCollection of SongData objects

This method was removed with version v4 of the package in favor for the more powerful collect method. The collection method can still be used by using the WithDeprecatedCollectionMethod trait:

use Spatie\LaravelData\Concerns\WithDeprecatedCollectionMethod;

class SongData extends Data
{
    use WithDeprecatedCollectionMethod;
    
    // ...
}

Please note that this trait will be removed in the next major version of the package.