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

use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
];

$users = UserDto::collection($data);
// Result: DataCollection of UserDto instances

From Eloquent Collection

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

Using DataCollection::make()

use event4u\DataHelpers\SimpleDto\DtoCollection;
use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'email' => 'john@example.com', 'age' => 30],
    ['name' => 'Jane', 'email' => 'jane@example.com', 'age' => 25],
];
$collection = DtoCollection::make($data, UserDto::class);

Collection Methods

Filter

use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 17],
    ['name' => 'Bob', 'age' => 30],
];

$users = UserDto::collection($data);
$adults = $users->filter(fn($user) => $user->age >= 18);
// Result: DataCollection with 2 items (John and Bob)

Map

use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 17],
    ['name' => 'Bob', 'age' => 30],
];

$users = UserDto::collection($data);
$adults = $users->filter(fn($user) => $user->age > 18);
$mapped = $adults->map(fn($user) => UserDto::fromArray([
    'name' => strtoupper($user->name),
    'age' => $user->age,
]));
// Result: DtoCollection with uppercase names for adults (JOHN and BOB)

First / Last

use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
];

$users = UserDto::collection($data);
$first = $users->first();
$last = $users->last();
// Result: $first->name = 'John', $last->name = 'Jane'

Count

use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
];

$users = UserDto::collection($data);
$count = $users->count();
// Result: 2

ToArray

use Tests\Utils\Docu\Dtos\UserDto;

$data = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
];

$users = UserDto::collection($data);
$array = $users->toArray();
// Result: [['name' => 'John', 'age' => 25], ['name' => 'Jane', 'age' => 30]]

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