Up to now, we've looked at individual concepts:

• a single user
• a single price
• a single ticket

But real programs rarely deal with just one thing.
They deal with many.

• Many users.
• Many orders.
• Many comments.
• Many coordinates.

When we have a group of similar things,
we need a way to hold them together.
That's where collections come in.

A collection is simply a container for multiple items of the same kind.

Imagine a small box on our desk labeled:

Users

Inside the box, we place:

• User #1
• User #2
• User #3

Each one is a folder (an entity).
The box is the collection.

The box doesn't care about the details inside each folder.
It only cares that:

• they are all users
• they belong together
• we can look through them
• we can add or remove them
• we can count them
• we can find one that matches a condition

A collection is simply
a group of similar objects.

In PHP, the simplest collection is an array:

$users = [
    $user1,
    $user2,
    $user3,
];

This works.
It's the simplest possible way to group things.

But arrays have a limitation:

→ They don't know what they contain.

We can accidentally mix types:

$users = [
    $user1,
    "hello",
    42,
];

Nothing stops us.
But our program becomes harder to reason about.

That's where
typed collections help.

Sometimes the group itself becomes meaningful.

For example:

• a list of users
• a list of orders
• a list of coordinates
• a list of money values

When the group has meaning, it deserves a name.

Here's a simple typed collection:

class UserCollection {
    /** @var User[] */
    private array $items = [];
 
    public function add(User $user): void {
        $this->items[] = $user;
    }
 
    public function all(): array {
        return $this->items;
    }
}

New to these tokens?
see the detailed breakdown here → UserCollection — Code explanation.

$users = new UserCollection();
$users->add($user1);
$users->add($user2);
$users->add($user3);
 
$list = $users->all();

This reads like a small story:

"Create a collection of users.
Add each user to the collection.
Retrieve the list when needed."

The collection becomes a meaningful part of our domain.

Collections give us:

• type safety
  we always know what’s inside
• predictable behavior
  filtering, sorting, mapping
• domain meaning
  the group becomes part of the vocabulary
• clarity
  our code reads like the problem we're solving

A UserCollection is easier to understand than “an array of things”.

A quick recap:

• Value Objects → small pieces of meaning
• Entities → long‑lived concepts with identity
• Collections → groups of similar things

Collections don't replace entities or value objects.
They hold them.

A collection is not a “thing” in the domain.
It's a group of things.

Use a collection when:

• we have many items of the same type
• the group itself has meaning
• we want to avoid mixing types
• we want predictable behavior
• we want to express intent clearly

Examples:

• UserCollection
• OrderCollection
• MoneyCollection
• CoordinateCollection

These help our code read like the domain.

If we only need:

• a quick list
• a temporary group
• a simple loop

…an array is enough.

Collections are for when
the group becomes meaningful.

A collection is a named box that holds many similar objects.
It guarantees what it contains.
It gives us predictable behavior.
It becomes part of our domain vocabulary.

Use collections when:

• the group matters
• the type matters
• the meaning matters

Collections help us code stay
clear, safe, and expressive.

The moment when “a list” becomes “a concept”

Conversation Example

We ask:

“Give the User a list of addresses.”

AI gives us:

public array $addresses = [];

Then we ask:

“Add a method to remove an address.”

AI writes array manipulation code.

Then we ask:

“Prevent duplicates.”

AI adds more array logic.

Then we ask:

“Sort addresses by type.”

AI adds even more array logic.

Now we feel the friction:

• too much array manipulation
• too many rules
• too much noise

This is the moment to say:

“Give me an AddressCollection that handles all of this.”

AI produces something like:

$addresses->add($address);
$addresses->remove($address);
$addresses->sorted();

Rule of Thumb

If we’re writing more than one array manipulation rule
— ask for a Collection.

_{Tony de Araujo —New York}

• Top↑
• Back to Topic ↔
• Home←