An aspect of Domain Driven Design (DDD)
that I find quite appealing is the differentiation between entities
and value objects. I don't think you even need to embrace DDD as a
whole to benefit from this distinction (I'm not saying you shouldn't
embrace DDD, just that this aspect of it stands on its own). If you
are using Doctrine 2 though, there is no native support for value
objects (not yet anyway), which leaves you
with the problem of mapping them yourself. In this post I will talk a
bit about the difference between entities and value objects and give
one suggestion of how to handle value objects when using Doctrine 2.

What is an entity?

An entity is a class that represents
something which has an identity independent of its properties. In
other words, even if some of its properties change, its identity
remains the same. Entities normally represent the fundamental
building blocks of your application.

For example, a Customer would be an
entity. A customer record might have various properties like name,
address, email address, order list, etc., but even if you change one
of those values (eg. if the customer moves house), it is still the
same customer.

What is a value object?

A value object is a class (usually
small, with just a few properties, and frequently used), that
represents a value which has no identity separate from its
properties. If any one of its properties change, it is no longer the
same value.

An example of a value object is an
address. If you change any part of an address, it becomes a different
address. Another example would be a price - it might have properties
for currency, amount, and payment frequency, but changing any of
those would yield a new price.

As such, value objects are immutable -
their properties cannot change (it is normal to use getters but not setters for the properties of value objects). If two value objects have
exactly the same properties, they can be regarded as equal.

Value objects can have methods, but the
behaviour of a method doesn't ever change the object's state. If a
method needs to change a property, it will return a brand new
instance of the value object instead of modifying the existing one.
Methods on a value object can also return other types of value of
course (eg. a boolean return value would be typical for a validate
method).

Can a Value Object have an Entity as a
property?

It doesn't happen very often, but there
is nothing wrong with referencing an entity from a value object -
having a reference to an entity does not force a value to become an
entity. For example, an address value object would typically include
a country property. Whilst this would normally be a string, your
application might need to have a Country class which has mutable
properties (such as whether the country is a member of the EU) and is
therefore an entity. But you could still have a country property on
your address value object, even if it refers to an entity (I will use this example in the sample code below).

Can an address/price/date range/etc. ever be
an Entity?

Yes! Whether something is an entity or
a value object depends on how you intend to use it. If you were
writing an application for a postal service or a town planner, an
address might be more than just a value - you might have the power to
change properties of an address without changing its identity (eg. if
you can assign house numbers or postcodes).

Why use value objects?

This is really two separate questions,
one of which is a little easier to answer than the other...

Why use value objects instead of scalar
values?

This is the easy one. You could have a
Customer class with properties for address_line_1, address_line_2,
etc. - each as a string. Or a phone number could be held as a string
with the area code in brackets. By collecting these properties
together into a single value object, or separating a string into
constituent parts as separate properties of a value object, it is not
hard to see that you will gain many OOP benefits. If there are
several pieces of data that go together to make a single domain
concept, they belong in an object. You can then perform computations
on that discrete set of data, validate it, re-use it, and extend it.
It also allows you to separate concerns - your entity does not have
to worry about any domain logic relating to the value, leading to
cleaner code.

Why use value objects instead of
Entities?

Why not just give everything an ID and
make it an entity? There's no technical reason why you couldn't have
an address ID for example, and even allow the properties to be
modified. However, although at first glance it might seem as though
separating out entities and value objects makes things more
complicated, it actually makes things simpler. Why give an address an
ID if it doesn't need one? It unnecessarily complicates your model,
and could also cause confusion as it is not clear how you intend the
data to be used. If something is defined as a value object, we know
what it is, that it will not change, and that another object of the
same type with the same properties is considered equal to it. This
gives us lots more information on how it is meant to be used - so the
conceptual difference is valuable in making your code understandable
and easy to maintain.

Having said that, if you are using an
ORM which does not support value objects (such as Doctrine 2), there
is indeed some additional complexity involved, as you need to provide
some way of mapping custom value objects to database columns
yourself. If you can do this in a way that will be easy to refactor
later (when hopefully the next version of Doctrine will support value
objects), it might still be worthwhile doing that extra legwork while
defining your entities so that you can reap the rewards of improved
code clarity and usability.

Using Value Objects with Doctrine 2

Let's take a simplified example. Here
is a basic Customer class, including phpDoc annotations for Doctrine
2 (the BaseEntity class it derives from [not shown] contains magic
methods __get and __set for accessing the protected properties, as
Doctrine 2 doesn't like you to use public properties):

Here we have an Address value object as
one of our properties, but we can't map it directly to a column,
because it is made up of several fields and Doctrine 2 currently
won't resolve them for us. We could give Address an ID and make it an
entity, and Doctrine 2 would then be able to map it, but if we want
to use a value object, we have to do our own mapping, which I will
come to in a minute. First, here is the Address class (the
BaseValueObject it derives from has a magic getter but no setter, so
the properties are read only):

As described above, the country
property of the Address value object here refers to an entity
(although it could very well refer to another value object, or just a
scalar value).

Now, to enable Doctrine 2 to persist
our Customer class, with its Address value object, we will need to
tell it how to map to columns to hold each part of the address. We
could use a custom mapping type
for this, but there is another way which is probably simpler and a
little more generic.

As Address is not an entity, and has no
identifier (ie. no primary key), the address data cannot be held in a
separate table - it will have to go in the same table as the Customer
entity. We could therefore just add the fields to our Customer entity
and map them to an accessor like this (note that here we do have a
setter as well as a getter for the address, because the Customer
entity is not immutable):

Here we have private properties to map
the individual parts of the address to database columns without
exposing these to the outside world (the magic getter in the base
class will not have access to them), but we have a public getter and
setter for the address value object.

This will work, but it doesn't look
very nice - our Customer class is now bloated with address mapping
code. Also, we might have other entities that also need an address,
and we don't want to have to copy and paste this all over the place.
This is where traits come in handy! We can use a trait to keep the
nasty mapping kludge out of our entity, and re-use it wherever an
address is needed:

The fly in the ointment

Aside from the fact that manually
mapping fields is a bit of a kludge in itself, there is another
problem here. What about cases where an entity needs more than one
address? Perhaps a billing address and shipping address for example?
We can't include the trait twice (well, we could use aliasing, but both would refer to the same values and would require a monumental kludge to differentiate), so we would have to add more traits
for the different address types. I still think that is better than
putting it all directly in the entity class, but it does smell a bit
iffy. What do you think? Is there a better way?

Update: Using Embeddables

If you can use Doctrine 2.5, this problem is easily solved using Embeddables. Here is how you would do the mapping for a customer address in Doctrine 2.5:

6 comments:

thank you for this great article. I linked it in my php port of the cargo sample used in Eric Eveans book. You can find it here: https://github.com/codeliner/php-ddd-cargo-sample/blob/master/docs/ChapterTwo-Review.md.

There is a new possibility available. Check out this pull request: https://github.com/doctrine/doctrine2/pull/835.Now, you can define Address as embeddable and use it as embedded value in your Customer class.

This was excellent! You really opened my eyes to what value objects are...I had always assumed they were in-memory objects useful for scalar properties such as partname or currency ...but what you described is what I have come to understand as "complex types" in .Net EF...brilliant this lets me solve an issue I have had for years in a work order management system and a dozen or more dates...All of which are interconnected and pain to maintain as part of the w/o object...