Collections

Learn how to work with collections of DTOs using DataCollection.

What are Collections?

Collections allow you to work with multiple DTO instances as a group:

$users = UserDTO::collection($userArray);
// DataCollection of UserDTO instances

$users->filter(fn($user) => $user->age > 18);
$users->map(fn($user) => $user->name);
$users->first();
$users->count();

Creating Collections

From Array

$data = [
    ['name' => 'John', 'email' => 'john@example.com'],
    ['name' => 'Jane', 'email' => 'jane@example.com'],
];

$users = UserDTO::collection($data);

From Eloquent Collection

$users = User::all();
$dtos = UserDTO::collection($users);

Using DataCollection::make()

use Event4u\DataHelpers\SimpleDTO\DataCollection;

$collection = DataCollection::make($data, UserDTO::class);

Collection Methods

Filter

$adults = $users->filter(fn($user) => $user->age >= 18);

Map

$names = $users->map(fn($user) => $user->name);

First / Last

$first = $users->first();
$last = $users->last();

Count

$count = $users->count();

ToArray

$array = $users->toArray();

Pagination

Basic Pagination

$paginated = UserDTO::paginatedCollection($users, page: 1, perPage: 10);
// [
//     'data' => [...],
//     'meta' => [
//         'current_page' => 1,
//         'per_page' => 10,
//         'total' => 100,
//         'last_page' => 10,
//     ],
// ]

Laravel Pagination

$users = User::paginate(10);
$dtos = UserDTO::collection($users);

Nested Collections

class OrderDTO extends SimpleDTO
{
    public function __construct(
        public readonly int $orderId,
        public readonly DataCollection $items,  // Collection of OrderItemDTO
    ) {}
}

$order = OrderDTO::fromArray([
    'orderId' => 123,
    'items' => [
        ['product' => 'Widget', 'quantity' => 2],
        ['product' => 'Gadget', 'quantity' => 1],
    ],
]);

Best Practices

Use Type Hints

// ✅ Good - with type hint
public readonly DataCollection $items;

// ❌ Bad - no type hint
public readonly $items;

Use Collection Methods

// ✅ Good - use collection methods
$adults = $users->filter(fn($user) => $user->age >= 18);

// ❌ Bad - manual loop
$adults = [];
foreach ($users as $user) {
    if ($user->age >= 18) {
        $adults[] = $user;
    }
}

Code Examples

The following working examples demonstrate this feature:

Data Collection - Working with collections
DTO Sorting - Sorting DTOs in collections

All examples are fully tested and can be run directly.

The functionality is thoroughly tested. Key test files:

CollectionTest.php - Collection tests

Run the tests:

# Run tests
task test:unit -- --filter=Collection