Value Objects

> A small simple object, like money or a date range, whose equality isn't based on identity.\ > -- Martin Fowler

A Value Object, as defined by Martin Fowler, is a small, simple object like money or a date range, whose equality isn't based on identity. In the Complex Heart Domain Model library, creating a Value Object is made easy through the use of the IsValueObject trait. This trait incorporates HasAttributes, HasInvariants, and HasEquality traits, streamlining the process of implementing robust Value Objects. Additionally, the ValueObject interface is available to expose the values and equals methods.

Getting Started

Creating a Value Object with the Complex Heart Domain Model library is straightforward. The library provides a trait named IsValueObject that, when used, adds three essential traits to your class:

• `HasAttributes`: Allows the Value Object to have attributes.
• `HasInvariants`: Enables the definition and validation of invariants.
• `HasEquality`: Facilitates the implementation of equality comparison.

Additionally, you can implement the ValueObject interface to expose the values and equals methods, providing a consistent interface for all Value Objects.

Example

Let's illustrate the implementation of a Color Value Object using the provided traits and interface:

use ComplexHeart\Contracts\Domain\Model\ValueObject;
use ComplexHeart\Domain\Model\IsValueObject;

class Color implements ValueObject 
{
    use IsValueObject;

    public function __construct(public string $value) 
    {
        $this->check();
    }
    
    protected function invariantValueMustBeHexadecimal(): bool 
    {
        return preg_match('/^#(?:[0-9a-fA-F]{3}){1,2}$/', $this->value) === 1;
    }
    
    public function __toString(): string 
    {
        return $this->value;
    }
}

// Instantiate a Color object
$red = new Color('#ff0000');

// Check equality with another Color object
$red->equals(new Color('#00ff00')); // returns false

// Retrieve the value of the Color object
$red->value; // returns #ff0000

// Exception handling for invariant violation
$magenta = new Color('ff00ff'); // throws InvariantViolation: Value must be hexadecimal.

Key Concepts

Attribute Initialization

Use the Constructor property promotion to initialize the attributes:

class SomeValueObject implements ValueObject 
{
    use IsValueObject;

    public function __construct(public string $value) 
    {
        $this->check();
    }
}

Alternatively, use the initialize method to set the initial values of the attributes. This ensures that the Value Object is properly initialized.

class SomeValueObject implements ValueObject 
{
    use IsValueObject;
    
    public string $value;

    public function __construct(string $value) 
    {
        $this->initialize(['value' => $value]);
    }
}

The initialize method takes an array of properties to hydrate the object. Whether the associative array contains additional properties, the initialize method selectively considers only those belonging to the object, matching the property names using the respective keys.

Immutability

Immutability is a fundamental characteristic of Value Objects. A Value Object is considered immutable when its state cannot be altered after instantiation. Once created, a Value Object retains its initial state throughout its lifecycle, ensuring stability and predictability in the domain model.

You can use readonly properties to ensure the state of the value object do not change.

class SomeValueObject implements ValueObject 
{
    use IsValueObject;

    public function __construct(public readonly string $value) 
    {
        $this->check();
    }
}

Alternatively, you can use the HasImmutability trait to enforce immutability. Just set the properties as private, the HasImmutability trait adds __set and __get magic methods to access the inner properties of the Value Object but blocking any attempt of updating the value.

class SomeValueObject implements ValueObject 
{
    use IsValueObject;

    public function __construct(private string $value) 
    {
        $this->check();
    }
    
    //...
}

$vo = new SomeValueObject('original');
$vo->value = 'updated'; //ImmutabilityError: Cannot modify property value from immutable SomeValueObject object.

Invariants

Implement the invariant methods to define rules that must be upheld by the Value Object. Invariants contribute to the integrity of the object's state. The invariant rules names must begin with the prefix invariant:

protected function invariantValueMustBeHexadecimal(): bool 
{
    return preg_match('/^#(?:[0-9a-fA-F]{3}){1,2}$/', $this->value) === 1;
}

An invariant function must adhere to the following criteria:

• It should either return a boolean value or throw an exception.
• Returning true signifies that the invariant has been successfully satisfied.
• Returning false, throwing an exception, or triggering an error in the invariant indicates that the invariant has not been met.

If boolean is returned the error message will be the invariant method name (PascalCase) in normal case. For example:

invariantValueMustBeHexadecimal => InvariantViolation: Value must be hexadecimal

If exception is thrown the error message will be the exception message. This allows you to customize the error messages.

Equality Check

Utilize the equals method inherited from the HasEquality trait to compare the equality of two Value Objects.

$red = new Color('#ff0000');
$red->equals(new Color('#00ff00')); // returns false
$red->equals(new stdClass()); // returns false
$red->equals('red'); // returns false

$anotherRed = new Color('#ff0000');
$red->equals($anotherRed); // return true