Writing value objects in PHP
Tags: php
Published: 2019-11-18 19:13:38

---
title: Writing value objects in PHP
published: true
date: 2019-11-03 16:30:00 UTC
tags: php
---

If you already have heard about [DDD (Domain-Driven Design)](https://en.wikipedia.org/wiki/Domain-driven_design), you probably also may have heard about Value Objects. It is one of the building blocks introduced by Eric Evans in ["the blue book"](https://www.amazon.com.br/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215).

A value object is a type which wraps data and is distinguishable only by its properties. Unlike an `Entity`, it doesn't have a unique identifier. Thus, **two value objects with the same property values should be considered equal**.

A good example of candidates for value objects are:

* phone number
* address
* price
* a commit hash
* a entity identifier
* and so on.

When designing a value object, you should pay attention to its three main characteristics: **immutability, structural equality, and self-validation**.

Here's an example:

```php
<?php declare(strict_types=1);

final class Price
{
    const USD = 'USD';
    const CAD = 'CAD';

    /** @var float */
    private $amount;

    /** @var string */
    private $currency;

    public function __construct(float $amount, string $currency = 'USD')
    {
        if ($amount < 0) {
            throw new \InvalidArgumentException("Amount should be a positive value: {$amount}.");
        }

        if (!in_array($currency, $this->getAvailableCurrencies())) {
            throw new \InvalidArgumentException("Currency should be a valid one: {$currency}.");
        }

        $this->amount = $amount;
        $this->currency = $currency;
    }

    private function getAvailableCurrencies(): array
    {
        return [self::USD, self::CAD];
    }

    public function getAmount(): float
    {
        return $this->amount;
    }

    public function getCurrency(): string
    {
        return $this->currency;
    }
}
```

## Immutability

Once you instantiate a value object, **it should be the same for the rest of the application lifecycle**. If you need to change its value, it should be done by entirely replacing that object.

Using mutable value objects is acceptable if you are using them **entirely within a local scope**, with only one reference to the object. Otherwise, you may have problems.

Taking the previous example, here's how you can update the amount of a `Price` type:

```php
<?php declare(strict_types=1);

final class Price
{
    // ...

    private function hasSameCurrency(Price $price): bool
    {
        return $this->currency === $price->currency;
    }

    public function sum(Price $price): self
    {
        if (!$this->hasSameCurrency($price)) {
            throw \InvalidArgumentException(
                "You can only sum values with the same currency: {$this->currency} !== {$price->currency}."
            );
        }

        return new self($this->amount + $price->amount, $this->currency);
    }
}
```

## Structural Equality

Value objects **don't have an identifier**. In other words, if two value objects have the same internal values, they must be considered equal. As PHP doesn't have a way to override the equality operator, you should implement it by yourself.

You can create a specialized method to do that:

```php
<?php declare(strict_types=1);

final class Price
{
    // ...

    public function isEqualsTo(Price $price): bool
    {
        return $this->amount === $price->amount && $this->currency === $price->currency;
    }
}
```

Another option is to create a hash based on its properties:

```php
<?php declare(strict_types=1);

final class Price
{
    // ...

    private function hash(): string
    {
        return md5("{$this->amount}{$this->currency}");
    }

    public function isEqualsTo(Price $price): bool
    {
        return $this->hash() === $price->hash();
    }
}
```

## Self-Validation

The **validation of a value object should occur on its creation**. If any of its properties are invalid, it should throw an exception. Putting this together with immutability, once you create a value object, you can be sure it will always be valid.

Taking the `Price` type example once again, it doesn't make sense to have a negative amount for the domain of the application:

```php
<?php declare(strict_types=1);

final class Price
{
    // ...

    public function __construct(float $amount, string $currency = 'USD')
    {
        if ($amount < 0) {
            throw new \InvalidArgumentException("Amount should be a positive value: {$amount}.");
        }

        if (!in_array($currency, $this->getAvailableCurrencies())) {
            throw new \InvalidArgumentException("Currency should be a valid one: {$currency}.");
        }

        $this->amount = $amount;
        $this->currency = $currency;
    }
}
```

## Using with Doctrine

Storing and retrieving value objects from the database using [Doctrine](https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/tutorials/embeddables.html) is quite easy using `Embeddable`s. According to the documentation, `Embeddable`s are not entities. But, you embed them in entities, which makes them perfect for dealing with value objects.

Let's suppose you have a `Product` class, and you would like to store the price in that class. You will end up with the following modeling:

```php
<?php declare(strict_types=1);

/** @Embeddable */
final class Price
{
    /** @Column(type="float") */
    private $amount;

    /** @Column(type="string") */
    private $currency;

    public function __construct(float $amount, string $currency = 'USD')
    {
        // ...

        $this->amount = $amount;
        $this->currency = $currency;
    }

    // ...
}

/** @Entity */
class Product
{
    /** @Embedded(class="Price") */
    private $price;

    public function __construct(Price $price)
    {
        $this->price = $price;
    }
}
```

Doctrine will automatically create the columns from the `Price` class into the table of the `Product` class. By default, it prefixes the database columns after the `Embeddable` class name, in this case: `price_amount` and `price_currency`.

## Conclusion

Value objects are useful for writing **clean code**. Instead of writing:

```php
public function addPhoneNumber(string $phone): void {}
```

You can write:

```php
public function addPhoneNumber(PhoneNumber $phone): void {}
```

Which makes it easy to read and reason about it, also you don't need to figure out which phone format you should use.

Since their attributes define them, and you can share them with other different entities, they can be cacheable forever.

They can help you to **reduce duplication**. Instead of having multiples `amount` and `currency` fields, you can use a pure `Price` class.

Of course, like everything in life, you **should not abuse** of value objects. Imagine you converting tons of objects to primitive values to store them in the database, or converting those back to value objects when fetching them from the database.Indeed, you can have performance issues. Also, having tons of granular value objects can bloat your codebase. 

With value objects, you can **reduce the [primitive obsession](https://refactoring.guru/smells/primitive-obsession)**. Use them to represent a field or group of fields of your domain that require validation or can cause ambiguity if you use primitive values.

Thanks for reading, and happy coding!

## Further Reading

* [Martin Fowler](https://twitter.com/martinfowler) has an article about value objects, check it out here: https://martinfowler.com/bliki/ValueObject.html