Value objects

July 16, 2015 at 7:49 AM - by Freek Lijten - 6 comments

Tags: OOP, DDD

Value objects are usually small objects and in the words of Martin Fowler: "Their key property is that they follow value semantics rather than reference semantics." This means their identity is not based on some sort of ID but on their properties.

Two "Freek Lijten" person objects might look the same but we'll need identifiers to be sure that we're not simply dealing with two people with the same name. Two color objects with red however will be the same, we do not need an identifier for those, the color is the identifier.

Value objects are generally (always) immutable. Most things that are modelled as a value object do not change. You can not change the meaning of an amount of Money for instance. You might be able to add or subtract an amount but that will result in a new amount of Money. 10 Euro will always be 10 Euro. opposed to that the person Freek may move, change his name or even gender all the while remaining the same "Freek".

This may seem a very small distinction but is actually very important.

Money

// Mutable, you never know what this Money object 
// is going to be  re-used

$Money = new Money();
$Money->setAmount(1000);
$Money->setCurrency(Money::EURO);
$Money->setPrecision(2);

$Money->setAmount(900);

// VS immutable Money with methods that result in new Money object,
// (more) error proof and more in line with the actual world.

$TenEuro = $Money = new Money(1000, Money::EURO, 2);
$OneEuro = new Money(100, Money::EURO, 2);
$NineEuro = $Money->subtract($OneEuro);

These are two ways of dealing with money. The first one is mutable. This will cause uncertainty on the value of the Money object. You can never know if it is changed somewhere or by what. In the best case this makes reasoning about this when debugging or trying to understand code harder. Worst case it creates nasty bugs exactly when you don't want it, when dealing with money.

The second example is an immutable variant of money. This type of approach to money also prevents you from spreading calculation logic all over the place. Adding, subtracting, multiplying and comparison are all operations on an amount of money resulting in a new amount of money. No more calculations all over the place, no CalculationService or whatever, just money you can do stuff with. I can not stress this enough, this all may seem like small gains, but it will change your code forever.

Email addresses

Email addresses are another obvious example of values that do not change. At the strangest they dissapear after years of not using your email address. What does change is the email address one considers to be "theirs".

To continue with our email address example, I've seen lots of code that validates email addresses over and over again. This strategy does not pay off once you miss checking a single location. If we introduce an EmailAddress object that only constructs with a valid email address we simply can not forget to check for validity:

if (emailAddressIsValid($emailAddress)
{
   // do stuff
}

// vs 

class EmailAddress
{
    /** @var string */
    private $emailAddress;

    public function __construct($emailAddress)
    {
        if ($this->emailAddressIsValid($emailAddress) {
            throw new InvalidEmailAddress();
        }
        $this->emailAddress = $emailAddress;
    }
    
    public getEmailAddress()
    {
        return $this->emailAddress;
    }
}

Everywhere we receive an EmailAddress object we are guaranteed an actual valid address which we do not need to check anymore.

And more...

Once you get into this mindset you'll find yourself wanting to make value objects for nearly anything. Principally you might want to make a value object of everything, only when you find no use for the object apart from being a carrier of a primitive type should you revert back to a simple primitive type. Almost anything has relations, cohesion or business logic attached to it.

Take the much used trio of firstname, insertion and lastname for instance. They are logically together and there is always stuff with formatting of full names, a complete lastname including insertions and more. So why wouldn't we put them together in a Name object?

class Name 
{
    public function __construct($firstName, $lastName, $insertion)
    {
        // set properties
    }

    public function getCompleteLastName()
    {
         if ( ! $this->insertion) {
             return $this->lastName;
         }
         return $this->insertion . ' ' .this->lastName;
    }
}

But even Id's can be useful as a value object. Even though ID's are generally something simple, at the very least being able to typehint different types of ID's can prevent subtle bugs where ID's are switched (think adding a product to a category). If you're lucky the product id is not also a category ID and vice versa (remember a lot of our id's are integers from an autoincrement column) but if both ID's exist then you will have a very intersting time finding out what happened :)

class ProductId 
{
    /** @var int */
    private $id;
   
    public function __construct($id)
    {
        $this->id = $id;
    }

    public function asInt()
    {
         return $this->id;
    }
}

/**
 * @var int $productId
 * @var int $categoryId
 */
function addProductToCategory($productId, $categoryId)
{

}

// vs

/**
 * @var ProductId $ProductId
 * @var CategoryId $CategoryId
 */
function addProductToCategory(ProductId $ProductId, CategoryId $CategoryId)
{

}

Concluding

All in all I find myself making value objects more and more. just remember the following:

1. A value object guarantees validity. If an email address is constructed with something else then a valid email address it is no email address. So constructing should fail. If we get an EmailAddress object we now know 100% sure that we consider this a valid address, no additional checks necessary.
2. A value object is THE location for stuff small business logic. Think formatting of names, adding or subtracting money, etc.
3. Value objects should be immutable, this will prevent bugs and confusion. It must be clear what a value object represents and what states are allowed.

I feel I need to mention the DDD-course Mathias Verraes though us since he made a lot of concepts that where since long floating helplessly trough my brain very clear. This course gave a huge boost to inspiration and ideas. He gives regular courses, check his webstite. You can also get him in-house which is what we did. Huge success :)