As developers, we often have a problematic relationship with primitives. We use a string for an email, a float for a price, and an int for a status. This is what we call Primitive Obsession—and it’s one of the common reasons why PHP codebases gradually become hard to maintain.
If you’ve been following my series on Refactoring & Patterns, you know I’m a fan of the Introduce Parameter Object pattern. But today, I want to go deeper and talk about one of the smallest, yet most powerful building blocks of clean architecture: Value Objects.
Previous article in this category: https://codecraftdiary.com/2026/04/11/fat-controller-laravel-refactor/
The “Price” of Primitive Obsession
Imagine you’re working on an e-commerce platform. You have a Product and a Discount.
public function applyDiscount(float $price, float $discountPercentage):float
{
if ($discountPercentage < 0 || $discountPercentage > 100) {
throw new InvalidArgumentException("Invalid discount");
}
return $price - ($price * ($discountPercentage / 100));
}At first glance, this looks fine. But in a real-world application, that $price is floating around (pun intended) everywhere.
- Is it USD or EUR?
- Does it include VAT?
- What about rounding?
And more importantly: what happens if you accidentally pass $discountPercentage as $price?
PHP won’t complain. Both are floats. You just sold a MacBook for $15.
On top of that, floats introduce precision issues, which makes them a poor choice for financial calculations in the first place.
What Exactly is a Value Object?
A Value Object (VO) is an object that is defined by its value rather than its identity.
Two Value Objects with the same data are considered equal—even if they are different instances.
In modern PHP (8.2+), a well-designed Value Object has three key characteristics:
- Immutability – once created, it cannot change
- Validation – it cannot exist in an invalid state
- Self-documentation – the type clearly expresses intent
A Better Approach: Explicit Domain Types
Let’s refactor the previous example.
final readonly class Price
{
public function __construct(
public int $amount, // in cents
public Currency $currency
) {
if ($this->amount < 0) {
throw new InvalidPriceException("Price cannot be negative.");
}
}
public function add(Price $other): Price
{
if ($this->currency !== $other->currency) {
throw new CurrencyMismatchException();
}
return new Price($this->amount + $other->amount, $this->currency);
}
public function equals(Price $other): bool
{
return $this->amount === $other->amount
&& $this->currency === $other->currency;
}
}A few important things are happening here:
- Encapsulation – price logic lives inside the
Priceclass - Type safety – you cannot mix currencies accidentally
- Immutability – every operation returns a new instance
- Precision – using integers avoids float rounding issues
Why This Matters (Especially Today)
With AI-assisted development becoming standard, types matter more than ever.
When you use primitives, tools like GitHub Copilot or ChatGPT have to guess intent.
When you use a Price or EmailAddress object, both humans and AI can:
- understand constraints immediately
- discover available behavior via methods
- avoid invalid states by design
You’re not just writing code—you’re defining a clear contract.
Real-World Refactoring: Email
How often have you written this?
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {<br> throw new Exception("Invalid email");<br>}If it appears in multiple places, that’s duplication—and a maintenance risk.
Let’s move that logic into a Value Object:
final readonly class EmailAddress
{
private string $value;
public function __construct(string $value)
{
if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
throw new InvalidEmailException($value);
}
$this->value = strtolower(trim($value));
}
public function getDomain(): string
{
return substr(strrchr($this->value, "@"), 1);
}
public function __toString(): string
{
return $this->value;
}
}Now your service layer becomes much cleaner:
// BEFORE
public function registerUser(string $email, string $password) { ... }
// AFTER
public function registerUser(EmailAddress $email, Password $password) { ... }The moment execution reaches registerUser, you already know the email is valid.
Validation is handled at the boundary of your system—not scattered across your codebase.
Logic-Heavy Value Objects
A common mistake is treating Value Objects as simple data containers.
In practice, they should encapsulate behavior related to that data.
Instead of passing:
string $startDate, string $endDateYou can model:
OrderDateRangeWith methods like:
overlapsWith()isWithinLastMonth()getDurationInDays()
This reduces cognitive load in your services and keeps domain logic where it belongs.
When NOT to Use Value Objects
Not everything needs to be a Value Object.
Ask yourself:
- Does this data have validation rules?
- Is it reused in multiple places?
- Does it represent a domain concept (SKU, IBAN, Email, Price)?
If the answer is yes, a Value Object is likely justified.
If you’re building a quick prototype, primitives are fine. Just be aware of the trade-offs.
Performance Considerations
A common concern used to be performance—creating many small objects instead of using primitives.
In modern PHP, object instantiation is highly optimized. The overhead is negligible compared to the cost of bugs caused by invalid states.
More importantly:
- immutable objects are predictable
- they eliminate side effects
- they are naturally safe in concurrent or async contexts
Summary
Refactoring toward Value Objects is one of the most effective ways to improve code quality.
It forces you to think in terms of domain concepts, not just data types.
Practical steps:
- Look at a complex service class
- Find a variable validated in multiple places
- Extract it into a readonly Value Object
- Move related logic into that object
You’ll end up with code that is easier to read, safer to modify, and harder to break.