Some data in your system isn't a “thing” with identity.
It doesn't have behavior beyond representing a value.
It doesn't change once created.

It's just a small piece of meaning.

That's a value object.

Value objects make your code clearer by giving names to important ideas
— currency, email addresses, coordinates, prices, dates, ranges, and other small concepts that deserve structure but not identity.

Consider these variables:

$price = 9.99;
$currency = "USD";

These work, but they hide meaning:

• Is the price always a float?
• Can the currency be anything?
• Should they always travel together?
• Can the value be invalid?

You're not dealing with “just numbers and strings”.
You're dealing with a concept — a monetary amount.

That's when a value object becomes the clearer choice.

A simple value object:

class Money {
    public function __construct(
        public float $amount,
        public string $currency
    ) {}
}

Now the idea has a name.
The structure is explicit.
The meaning is visible.

You've turned two loose primitives into a single, coherent concept.

Value objects give you:

• clarity — the concept is named
• safety — invalid combinations are impossible
• immutability — the value doesn't change
• expressiveness — the code reads like the domain
• correctness — rules live where they belong

They are small, intentional, and precise.

Value objects should not change after creation.

class Email {
    public function __construct(
        public string $address
    ) {
        // validation belongs here
    }
}

If you need a different email, you create a new instance.
This makes your code predictable and easier to reason about.

Immutability is not a restriction
— it's clarity.

Value objects can carry small pieces of logic that belong to the concept:

class Money {
    public function __construct(
        public float $amount,
        public string $currency
    ) {}
 
    public function add(Money $other): Money {
        return new Money(
            $this->amount + $other->amount,
            $this->currency
        );
    }
}

The rule lives with the value.
Not scattered across your code.

Use a value object when the data:

• represents a small concept
• has meaning
• has rules
• should not change
• appears in multiple places
• deserves a name

Examples:

• Email
• Money
• Coordinates
• DateRange
• Temperature
• Percentage

These are not “entities”.
They're pieces of meaning.

Avoid value objects when the data is:

• trivial
• short‑lived
• configuration‑like
• not meaningful
• not reused

Not everything deserves a class.
Use value objects when they clarify,
not when they complicate.

Value objects are the quiet vocabulary of your system.
They turn raw values into named meaning.

Use them when:

• the value has structure
• the value has rules
• the value should be immutable
• the value appears often

They make your code read like the domain
— not like plumbing.

_{Tony de Araujo —New York}

• Top↑
• Back to Topic ↔
• Home←